Testing

Testing Clerk Authentication: Mock User Sessions, useAuth Hook, and Webhooks

HelpMeTest

HelpMeTest

— 5 min read
Testing Clerk Authentication: Mock User Sessions, useAuth Hook, and Webhooks

Clerk is a popular authentication platform that handles sign-up, sign-in, user management, and session management for you. Testing Clerk-authenticated apps is non-trivial because Clerk wraps your app in providers and its hooks make real API calls. This guide shows you how to test Clerk integrations without hitting Clerk's API.

The Core Challenge with Clerk Testing

Clerk's React SDK wraps your app in <ClerkProvider> and exposes auth state through hooks like useAuth(), useUser(), and useClerk(). In tests, you need to:

  1. Mock the Clerk provider so components don't try to contact Clerk's servers
  2. Control the auth state (authenticated, unauthenticated, loading)
  3. Test route protection (redirects for unauthenticated users)
  4. Test webhook handlers on the backend

Mocking the Clerk Provider

Clerk provides a @clerk/testing package specifically for this:

npm install --save-dev @clerk/testing

For Jest/React Testing Library:

// test-utils/clerk-setup.js
import { ClerkProvider } from '@clerk/testing/react';

export function renderWithClerk(component, { user = null } = {}) {
  const mockClerk = {
    user: user,
    session: user ? { id: 'session-123', status: 'active' } : null,
    isLoaded: true,
    isSignedIn: !!user,
  };

  return render(
    <ClerkProvider {...mockClerk}>
      {component}
    </ClerkProvider>
  );
}

For a more complete mock without @clerk/testing:

// test-utils/clerk-mocks.js
const mockUseAuth = jest.fn();
const mockUseUser = jest.fn();
const mockUseClerk = jest.fn();

jest.mock('@clerk/nextjs', () => ({
  useAuth: () => mockUseAuth(),
  useUser: () => mockUseUser(),
  useClerk: () => mockUseClerk(),
  ClerkProvider: ({ children }) => children,
  SignIn: () => <div data-testid="sign-in-form" />,
  SignUp: () => <div data-testid="sign-up-form" />,
  UserButton: () => <button>User Menu</button>,
}));

export { mockUseAuth, mockUseUser, mockUseClerk };

// Helper functions for common states
export function mockAuthenticatedUser(overrides = {}) {
  const user = {
    id: 'user_2abc123',
    firstName: 'Jane',
    lastName: 'Smith',
    emailAddresses: [{ emailAddress: 'jane@example.com', id: 'em_1' }],
    primaryEmailAddress: { emailAddress: 'jane@example.com' },
    publicMetadata: {},
    privateMetadata: {},
    ...overrides,
  };

  mockUseAuth.mockReturnValue({
    isLoaded: true,
    isSignedIn: true,
    userId: user.id,
    sessionId: 'sess_2xyz789',
    getToken: jest.fn().mockResolvedValue('mock-jwt-token'),
  });

  mockUseUser.mockReturnValue({
    isLoaded: true,
    isSignedIn: true,
    user,
  });

  return user;
}

export function mockUnauthenticatedState() {
  mockUseAuth.mockReturnValue({
    isLoaded: true,
    isSignedIn: false,
    userId: null,
    sessionId: null,
    getToken: jest.fn().mockResolvedValue(null),
  });

  mockUseUser.mockReturnValue({
    isLoaded: true,
    isSignedIn: false,
    user: null,
  });
}

export function mockLoadingState() {
  mockUseAuth.mockReturnValue({ isLoaded: false, isSignedIn: false, userId: null });
  mockUseUser.mockReturnValue({ isLoaded: false, isSignedIn: false, user: null });
}

Testing the useAuth Hook

import { mockAuthenticatedUser, mockUnauthenticatedState, mockLoadingState } from '../test-utils/clerk-mocks';
import Dashboard from '../components/Dashboard';

describe('Dashboard authentication', () => {
  test('shows loading state while Clerk initializes', () => {
    mockLoadingState();
    render(<Dashboard />);
    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
  });

  test('shows sign-in prompt for unauthenticated users', () => {
    mockUnauthenticatedState();
    render(<Dashboard />);
    expect(screen.getByTestId('sign-in-form')).toBeInTheDocument();
    expect(screen.queryByTestId('dashboard-content')).not.toBeInTheDocument();
  });

  test('renders dashboard content for authenticated users', () => {
    mockAuthenticatedUser({ firstName: 'Jane', lastName: 'Smith' });
    render(<Dashboard />);
    expect(screen.getByTestId('dashboard-content')).toBeInTheDocument();
    expect(screen.getByText('Welcome, Jane!')).toBeInTheDocument();
  });

  test('displays user email in profile section', () => {
    mockAuthenticatedUser({ firstName: 'John' });
    render(<Dashboard />);
    expect(screen.getByText('jane@example.com')).toBeInTheDocument();
  });
});

Testing Protected Routes

For Next.js apps using Clerk middleware:

// Testing the middleware behavior (in unit tests)
import { authMiddleware } from '@clerk/nextjs/server';
import { NextRequest } from 'next/server';

jest.mock('@clerk/nextjs/server', () => ({
  authMiddleware: jest.fn((config) => {
    return (req) => {
      // Simulate Clerk's middleware logic
      const token = req.headers.get('Authorization');
      if (!token && !config.publicRoutes?.includes(req.nextUrl.pathname)) {
        return new Response(null, {
          status: 302,
          headers: { Location: '/sign-in' },
        });
      }
      return new Response(null, { status: 200 });
    };
  }),
}));

test('redirects unauthenticated users from protected routes', async () => {
  const req = new NextRequest('http://localhost:3000/dashboard');
  const middleware = authMiddleware({
    publicRoutes: ['/sign-in', '/sign-up', '/'],
  });
  
  const response = await middleware(req);
  
  expect(response.status).toBe(302);
  expect(response.headers.get('Location')).toContain('/sign-in');
});

test('allows access to public routes without auth', async () => {
  const req = new NextRequest('http://localhost:3000/sign-in');
  const middleware = authMiddleware({
    publicRoutes: ['/sign-in', '/sign-up', '/'],
  });
  
  const response = await middleware(req);
  
  expect(response.status).toBe(200);
});

Testing API Route Protection

For Next.js API routes using getAuth:

import { getAuth } from '@clerk/nextjs/server';
import { NextRequest } from 'next/server';

// Mock the Clerk server SDK
jest.mock('@clerk/nextjs/server', () => ({
  getAuth: jest.fn(),
}));

import handler from '../app/api/protected/route';

describe('Protected API route', () => {
  test('returns 401 for unauthenticated requests', async () => {
    getAuth.mockReturnValue({ userId: null });
    
    const req = new NextRequest('http://localhost:3000/api/protected');
    const response = await handler(req);
    
    expect(response.status).toBe(401);
    const body = await response.json();
    expect(body.error).toBe('Unauthorized');
  });

  test('returns data for authenticated requests', async () => {
    getAuth.mockReturnValue({ userId: 'user_2abc123' });
    
    const req = new NextRequest('http://localhost:3000/api/protected');
    const response = await handler(req);
    
    expect(response.status).toBe(200);
    const body = await response.json();
    expect(body.data).toBeDefined();
  });
});

Testing Clerk Webhooks

Clerk sends webhooks for user lifecycle events. Test your webhook handlers:

import { Webhook } from 'svix';
import handler from '../app/api/webhooks/clerk/route';

jest.mock('svix');

describe('Clerk webhook handler', () => {
  const validSecret = 'whsec_test-signing-secret';
  
  beforeEach(() => {
    process.env.CLERK_WEBHOOK_SECRET = validSecret;
  });

  function createWebhookPayload(eventType, data) {
    return {
      type: eventType,
      data,
      object: 'event',
      timestamp: Date.now(),
    };
  }

  test('handles user.created event — creates user in database', async () => {
    const mockVerify = jest.fn().mockReturnValue(
      createWebhookPayload('user.created', {
        id: 'user_2abc123',
        first_name: 'Jane',
        last_name: 'Smith',
        email_addresses: [{ email_address: 'jane@example.com', id: 'em_1' }],
        primary_email_address_id: 'em_1',
        created_at: Date.now(),
      })
    );
    
    Webhook.mockImplementation(() => ({ verify: mockVerify }));
    
    const mockCreateUser = jest.fn().mockResolvedValue({ id: 'db-user-1' });
    jest.mock('../lib/db', () => ({ users: { create: mockCreateUser } }));

    const request = new Request('http://localhost/api/webhooks/clerk', {
      method: 'POST',
      headers: {
        'svix-id': 'msg_1',
        'svix-timestamp': String(Date.now()),
        'svix-signature': 'v1,test-signature',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(createWebhookPayload('user.created', {
        id: 'user_2abc123',
        first_name: 'Jane',
        last_name: 'Smith',
        email_addresses: [{ email_address: 'jane@example.com', id: 'em_1' }],
        primary_email_address_id: 'em_1',
        created_at: Date.now(),
      })),
    });

    const response = await handler(request);
    
    expect(response.status).toBe(200);
    expect(mockCreateUser).toHaveBeenCalledWith({
      clerkId: 'user_2abc123',
      name: 'Jane Smith',
      email: 'jane@example.com',
    });
  });

  test('returns 400 for invalid webhook signature', async () => {
    Webhook.mockImplementation(() => ({
      verify: jest.fn().mockImplementation(() => {
        throw new Error('Invalid signature');
      }),
    }));

    const request = new Request('http://localhost/api/webhooks/clerk', {
      method: 'POST',
      headers: {
        'svix-id': 'msg_bad',
        'svix-timestamp': String(Date.now()),
        'svix-signature': 'v1,bad-signature',
      },
      body: '{}',
    });

    const response = await handler(request);
    expect(response.status).toBe(400);
  });

  test('handles user.deleted event — removes user from database', async () => {
    const mockVerify = jest.fn().mockReturnValue(
      createWebhookPayload('user.deleted', { id: 'user_2abc123', deleted: true })
    );
    Webhook.mockImplementation(() => ({ verify: mockVerify }));
    
    // Test deletion logic...
    const response = await handler(/* request with delete event */);
    expect(response.status).toBe(200);
  });
});

Testing Organization Features

For B2B apps using Clerk's organization support:

// Mock organization context
export function mockOrganizationMember(role = 'member') {
  mockUseAuth.mockReturnValue({
    isLoaded: true,
    isSignedIn: true,
    userId: 'user_2abc123',
    orgId: 'org_abc456',
    orgRole: `org:${role}`,
    orgSlug: 'acme-corp',
    getToken: jest.fn().mockResolvedValue('mock-token'),
  });
}

test('shows admin controls for org admins', () => {
  mockOrganizationMember('admin');
  render(<OrganizationSettings />);
  expect(screen.getByRole('button', { name: 'Delete Organization' })).toBeInTheDocument();
});

test('hides admin controls for regular members', () => {
  mockOrganizationMember('member');
  render(<OrganizationSettings />);
  expect(screen.queryByRole('button', { name: 'Delete Organization' })).not.toBeInTheDocument();
});

E2E Testing with HelpMeTest

Mock-based tests verify your auth logic, but real Clerk auth flows — OAuth redirects, session persistence, MFA — need browser-level testing. HelpMeTest handles this with saved auth states:

Save As ClerkAdminUser
Go to https://your-app.com/sign-in
Enter admin@example.com in the email field
Enter test-password in the password field
Click Sign In
Verify redirect to /dashboard
Verify user menu shows admin name

Then in subsequent tests:

As ClerkAdminUser
Go to https://your-app.com/admin/settings
Verify admin settings panel is visible

HelpMeTest saves the Clerk session cookie, so you authenticate once and reuse across all tests — exactly like production user behavior.

Common Pitfalls

Don't test Clerk's UI components. Clerk's <SignIn />, <SignUp />, and <UserButton /> are black boxes — testing them is testing Clerk, not your app. Mock them and focus on what your code does with the auth state.

Mock getToken in API tests. If your components call getToken() to get a JWT for API requests, ensure your mock returns a consistent value. Failing to do so causes undefined token bugs.

Test all three auth states. Loading, authenticated, and unauthenticated are all distinct states. Many bugs only appear in the loading state (flashes of wrong content) or when transitioning between states.

Summary

Testing Clerk-authenticated apps requires:

  1. Mocking Clerk hooks — useAuth, useUser, useClerk with controlled return values
  2. Testing three auth states — loading, authenticated, unauthenticated
  3. Route protection tests — middleware redirects, API route authorization
  4. Webhook handler tests — signature validation, event type handling, database sync
  5. Organization/role tests — feature flags based on Clerk roles
  6. E2E monitoring — HelpMeTest for real Clerk session flows in browsers

Read more