How to Test Clerk Sign-In with Playwright: Complete 2026 Guide

The most common Clerk sign-in flow asks the user for their email address, sends a one-time verification code, and then asks the user to enter that code. Testing this end-to-end requires a way to retrieve the verification code programmatically. In development mode, Clerk provides a predictable code or you can retrieve it via the Backend API.

Goal

Sign in with an existing test user using the email and verification code flow, land on the authenticated dashboard, and confirm the session is active.

Playwright vs Assrt

import { test, expect } from '@playwright/test';
import { clerkClient } from '@clerk/clerk-sdk-node';

test('email + verification code sign-in', async ({ page }) => {
  const testEmail = process.env.TEST_USER_EMAIL!;

  // 1. Navigate to sign-in page
  await page.goto('/sign-in');

  // 2. Clerk renders its own component. Wait for the email input.
  const emailInput = page.getByLabel('Email address');
  await expect(emailInput).toBeVisible({ timeout: 10_000 });
  await emailInput.fill(testEmail);

  // 3. Click continue to trigger the verification code
  await page.getByRole('button', { name: /continue/i }).click();

  // 4. Wait for the code input to appear
  const codeInput = page.getByLabel('Enter verification code');
  await expect(codeInput).toBeVisible({ timeout: 10_000 });

  // 5. Use the dev mode test code
  const code = '424242';
  await codeInput.fill(code);

  // 6. Click the verify button
  await page.getByRole('button', { name: /verify/i }).click();

  // 7. Assert we are redirected to the dashboard
  await page.waitForURL(/\/dashboard/, { timeout: 15_000 });
  await expect(page.getByText(/welcome/i)).toBeVisible();
});

Clerk's OAuth flow is a three-hop redirect. Your app sends the user to clerk.{app}.com, which redirects to accounts.google.com, which redirects back to Clerk, which finally redirects back to your app. Each hop is a full page navigation across a different origin. Playwright handles this natively, but the timing and the Google consent screen make this the hardest scenario to stabilize.

Why OAuth Tests Are Fragile

Google's consent screen is not under your control. It changes layout, adds CAPTCHAs for suspicious login patterns, and blocks automated browsers when it detects Playwright. For CI, the recommended approach is to use Clerk Testing Tokens (Section 7) to bypass OAuth entirely. For local development and visual regression testing, the approach below works reliably with a dedicated Google test account.

Playwright Implementation

import { test, expect } from '@playwright/test';

test('OAuth sign-in via Google', async ({ page }) => {
  // 1. Navigate to sign-in and click the Google button
  await page.goto('/sign-in');
  await page.getByRole('button', { name: /continue with google/i }).click();

  // 2. Wait for the redirect to Google's consent screen.
  //    This crosses through clerk.yourapp.com first.
  await page.waitForURL(/accounts\.google\.com/, { timeout: 15_000 });

  // 3. Fill Google credentials
  await page.getByLabel('Email or phone').fill(process.env.GOOGLE_TEST_EMAIL!);
  await page.getByRole('button', { name: /next/i }).click();

  await page.getByLabel('Enter your password').fill(
    process.env.GOOGLE_TEST_PASSWORD!
  );
  await page.getByRole('button', { name: /next/i }).click();

  // 4. Handle the consent/allow screen if it appears
  const allowButton = page.getByRole('button', { name: /allow|continue/i });
  if (await allowButton.isVisible({ timeout: 5_000 }).catch(() => false)) {
    await allowButton.click();
  }

  // 5. Wait for the full redirect chain to complete
  //    Google -> Clerk -> Your app
  await page.waitForURL(/\/dashboard/, { timeout: 30_000 });

  // 6. Assert authenticated state
  await expect(page.getByText(/welcome/i)).toBeVisible();
});

Assrt Equivalent

# scenarios/clerk-google-oauth.assrt
describe: Sign in through Google OAuth via Clerk

given:
  - I am on the sign-in page
  - I have valid Google test credentials

steps:
  - click "Continue with Google"
  - wait for Google's login page to load
  - fill in the Google email and password
  - click through the consent screen if it appears
  - wait for the redirect back to my app

expect:
  - I am on /dashboard within 30 seconds
  - the page shows a welcome message
  - the user profile shows the Google email

Clerk supports phone number sign-in where the user enters their phone number and receives an SMS with a verification code. This flow is similar to email verification, but retrieving the SMS code in a test environment requires a different strategy. In Clerk's development mode, you can use a predictable test code or retrieve it through the Backend API.

Playwright Implementation

import { test, expect } from '@playwright/test';

test('phone number + SMS code sign-in', async ({ page }) => {
  const testPhone = process.env.TEST_USER_PHONE!;

  // 1. Navigate to sign-in
  await page.goto('/sign-in');

  // 2. Switch to phone number sign-in if email is default
  const phoneTab = page.getByRole('button', { name: /phone/i });
  if (await phoneTab.isVisible({ timeout: 3_000 }).catch(() => false)) {
    await phoneTab.click();
  }

  // 3. Enter phone number
  const phoneInput = page.getByLabel(/phone number/i);
  await expect(phoneInput).toBeVisible({ timeout: 10_000 });
  await phoneInput.fill(testPhone);

  // 4. Click continue to trigger SMS
  await page.getByRole('button', { name: /continue/i }).click();

  // 5. Wait for code input
  const codeInput = page.getByLabel(/verification code|enter code/i);
  await expect(codeInput).toBeVisible({ timeout: 10_000 });

  // 6. In dev mode, Clerk uses a predictable test code
  //    For production-like testing, use an SMS receiving service
  const smsCode = '424242';
  await codeInput.fill(smsCode);

  // 7. Submit the code
  await page.getByRole('button', { name: /verify|continue/i }).click();

  // 8. Assert authenticated state
  await page.waitForURL(/\/dashboard/, { timeout: 15_000 });
  await expect(page.getByText(/welcome/i)).toBeVisible();
});

Assrt Equivalent

# scenarios/clerk-phone-sms-login.assrt
describe: Sign in with phone number and SMS verification code

given:
  - I am on the sign-in page
  - a test user exists with a known phone number

steps:
  - switch to phone number sign-in if needed
  - fill the phone number field with the test phone number
  - click "Continue"
  - wait for the verification code input
  - fill the code with 424242
  - click "Verify"

expect:
  - I am redirected to /dashboard within 15 seconds
  - the page shows a welcome message

The sign-up flow is distinct from sign-in because it creates a new user and often requires email verification before the account is active. Clerk's <SignUp /> component handles collecting the email, password (if configured), and any additional fields you have required. After submission, Clerk sends a verification email, and the user must enter the code to complete registration.

Playwright Implementation

import { test, expect } from '@playwright/test';
import { clerkClient } from '@clerk/clerk-sdk-node';

test('new user sign-up with email verification', async ({ page }) => {
  const uniqueEmail = `signup+${Date.now()}@yourapp.com`;

  // 1. Navigate to sign-up
  await page.goto('/sign-up');

  // 2. Fill in the sign-up form
  const emailInput = page.getByLabel('Email address');
  await expect(emailInput).toBeVisible({ timeout: 10_000 });
  await emailInput.fill(uniqueEmail);

  // Fill password if your instance requires it
  const passwordInput = page.getByLabel('Password');
  if (await passwordInput.isVisible({ timeout: 3_000 }).catch(() => false)) {
    await passwordInput.fill('SecureTestPass123!');
  }

  // Fill name fields if required
  const firstNameInput = page.getByLabel('First name');
  if (await firstNameInput.isVisible({ timeout: 2_000 }).catch(() => false)) {
    await firstNameInput.fill('Test');
    await page.getByLabel('Last name').fill('User');
  }

  // 3. Submit the form
  await page.getByRole('button', { name: /continue|sign up/i }).click();

  // 4. Wait for email verification step
  const codeInput = page.getByLabel(/verification code/i);
  await expect(codeInput).toBeVisible({ timeout: 10_000 });

  // 5. Enter the dev mode test code
  await codeInput.fill('424242');
  await page.getByRole('button', { name: /verify/i }).click();

  // 6. Assert the new user lands on the onboarding or dashboard page
  await page.waitForURL(/\/(dashboard|onboarding)/, { timeout: 15_000 });

  // 7. Clean up: delete the test user after the test
  const users = await clerkClient.users.getUserList({
    emailAddress: [uniqueEmail],
  });
  if (users.data.length > 0) {
    await clerkClient.users.deleteUser(users.data[0].id);
  }
});

Assrt Equivalent

# scenarios/clerk-signup-email.assrt
describe: New user sign-up with email verification

given:
  - I am on the sign-up page
  - I use a fresh random email address

steps:
  - fill the email address field
  - fill the password with "SecureTestPass123!"
  - fill first name with "Test" and last name with "User"
  - click "Continue"
  - wait for the verification code input
  - fill the code with 424242
  - click "Verify"

expect:
  - I am redirected to /dashboard or /onboarding within 15 seconds
  - the new user account is created in Clerk

Clerk Testing Tokens are the recommended approach for CI pipelines. Instead of driving the sign-in UI, you create an authenticated session programmatically by setting the Clerk session cookie before your test navigates to a protected page. This eliminates flakiness from component rendering timing, code retrieval, and OAuth redirects.

How Testing Tokens Work

You call the Clerk Backend API to create a sign-in token for a specific user. Then you use that token to set the session cookie in Playwright's browser context. When the browser navigates to your app, Clerk recognizes the session and treats the user as authenticated. No UI interaction is needed.

Playwright Implementation

import { test, expect } from '@playwright/test';

// Global setup: create an authenticated state file
// test/setup/clerk-auth.ts
import { clerkClient } from '@clerk/clerk-sdk-node';
import { chromium } from '@playwright/test';

async function globalSetup() {
  const browser = await chromium.launch();
  const context = await browser.newContext();
  const page = await context.newPage();

  // 1. Create a sign-in token for the test user
  const signInToken = await clerkClient.signInTokens.createSignInToken({
    userId: process.env.TEST_USER_ID!,
    expiresInSeconds: 300,
  });

  // 2. Navigate to the sign-in token URL
  //    Clerk provides a URL that consumes the token and creates a session
  await page.goto(
    `${process.env.APP_BASE_URL}/sign-in#/factor-one?__clerk_ticket=${signInToken.token}`
  );

  // 3. Wait for the redirect to complete and session to be set
  await page.waitForURL(/\/dashboard/, { timeout: 15_000 });

  // 4. Save the authenticated state
  await context.storageState({ path: './test/.auth/clerk-session.json' });

  await browser.close();
}

export default globalSetup;

// Use the saved state in your tests
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  globalSetup: './test/setup/clerk-auth.ts',
  projects: [
    {
      name: 'authenticated',
      use: {
        storageState: './test/.auth/clerk-session.json',
      },
    },
    {
      name: 'unauthenticated',
      // No storageState: tests run without a session
    },
  ],
});

// Now your tests start already signed in
test('authenticated user can access dashboard', async ({ page }) => {
  await page.goto('/dashboard');

  // No sign-in needed. The session cookie is already set.
  await expect(page.getByRole('heading', { name: /dashboard/i }))
    .toBeVisible();
  await expect(page.getByText(/welcome back/i)).toBeVisible();
});

Assrt Equivalent

# scenarios/clerk-testing-token-ci.assrt
describe: Authenticated dashboard access via Testing Token

given:
  - I am signed in as the test user (via Clerk Testing Token)

steps:
  - navigate to /dashboard

expect:
  - the page shows the dashboard heading
  - the page shows a welcome back message
  - no sign-in redirect occurs

Clerk supports multi-session mode where users can be signed into multiple accounts simultaneously and switch between them. Testing session management is critical for apps that use this feature, and it is also important to verify that sign-out actually invalidates the session and redirects to the correct page.

Playwright Implementation: Sign Out

import { test, expect } from '@playwright/test';

test('sign out invalidates session and redirects', async ({ page }) => {
  // Start with an authenticated session (via storageState)
  await page.goto('/dashboard');
  await expect(page.getByRole('heading', { name: /dashboard/i }))
    .toBeVisible();

  // 1. Open the user menu (Clerk's UserButton component)
  await page.getByRole('button', { name: /open user menu|user button/i })
    .click();

  // 2. Click sign out in the dropdown
  await page.getByRole('menuitem', { name: /sign out/i }).click();

  // 3. Assert redirect to sign-in page
  await page.waitForURL(/\/sign-in/, { timeout: 10_000 });

  // 4. Verify the session is actually gone by trying to access
  //    a protected route
  await page.goto('/dashboard');
  await page.waitForURL(/\/sign-in/, { timeout: 10_000 });
});

Playwright Implementation: Account Switching

test('switch between multiple signed-in accounts', async ({ page }) => {
  // Assumes multi-session is enabled and two users are signed in
  await page.goto('/dashboard');

  // 1. Open the user menu
  await page.getByRole('button', { name: /open user menu/i }).click();

  // 2. Look for the account switcher section
  const otherAccount = page.getByRole('menuitem', {
    name: /switch account|other account/i,
  });
  await expect(otherAccount).toBeVisible();
  await otherAccount.click();

  // 3. Select the second account
  const secondAccount = page.getByText(process.env.SECOND_USER_EMAIL!);
  await expect(secondAccount).toBeVisible({ timeout: 5_000 });
  await secondAccount.click();

  // 4. Assert the dashboard now shows the second user's data
  await expect(page.getByText(process.env.SECOND_USER_EMAIL!))
    .toBeVisible({ timeout: 10_000 });
});

Assrt Equivalent

# scenarios/clerk-session-management.assrt
describe: Sign out and verify session invalidation

given:
  - I am signed in on the dashboard

steps:
  - open the user menu
  - click "Sign out"

expect:
  - I am redirected to /sign-in
  - navigating to /dashboard redirects me back to /sign-in
  - the session cookie is removed