Clerk authentication can be tested with Playwright in two ways: use Clerk's official testing helpers to create an authenticated browser quickly, or interact with the sign-in UI to verify the customer journey. A useful test set contains both because the helper intentionally bypasses verification steps that the UI test is meant to cover.

Clerk's @clerk/testing package provides Playwright setup, sign-in, sign-out, and testing-token helpers. Clerk also supports testing tokens on production instances for browser automation that would otherwise trigger bot protection.

Key takeaways

  • Use Clerk's helper for authenticated test setup and a separate UI test for sign-in behavior.
  • Call clerkSetup() before other Clerk Playwright helpers.
  • Use a dedicated test email and keep CLERK_SECRET_KEY out of source control.
  • Verify a protected application element after sign-in, not only the Clerk component.
  • Know that helper-based sign-in bypasses verification and MFA.

What does Clerk's Playwright integration provide?

The official Clerk Playwright documentation covers testing tokens and helper functions. The main pieces are:

  • clerkSetup() prepares the test run.
  • clerk.signIn() authenticates a known user.
  • clerk.signOut() terminates a Clerk session.
  • clerk.loaded() checks that the Clerk client finished loading.
  • setupClerkTestingToken() lets automated browsers bypass Clerk bot protection.

The recommended email-address sign-in creates a server-side token and requires CLERK_SECRET_KEY. Clerk documents that this route bypasses verification and MFA, which is useful for test setup but unsuitable as the only authentication test.

Install and configure Clerk's Playwright helpers

Install the testing package next to Playwright in the application repository:

npm install --save-dev @playwright/test @clerk/testing

Create a setup project that runs before the authenticated tests:

// tests/global.setup.js
import { clerkSetup } from '@clerk/testing/playwright'
import { test as setup } from '@playwright/test'

setup.describe.configure({ mode: 'serial' })

setup('configure Clerk testing', async () => {
  await clerkSetup()
})

Provide the publishable and secret keys through the local or CI environment. Do not commit them to playwright.config.

Sign in a Clerk user without using the UI

Use helper-based sign-in when the test concerns the protected application rather than the login form:

import { test, expect } from '@playwright/test'
import { clerk } from '@clerk/testing/playwright'

test('authenticated user can open account settings', async ({ page }) => {
  await page.goto(process.env.APP_ORIGIN)

  await clerk.signIn({
    page,
    emailAddress: process.env.CLERK_TEST_EMAIL,
  })

  await page.goto(`${process.env.APP_ORIGIN}/account`)
  await expect(page.getByRole('heading', { name: /account settings/i }))
    .toBeVisible()
})

Clerk recommends using a +clerk_test email address for test users. Its documentation says this suffix suppresses email delivery, including verification and new-device notifications.

Reuse Clerk authentication state

When many tests share the same role, authenticate once and save the browser state:

import path from 'path'
import { clerk } from '@clerk/testing/playwright'
import { test as setup, expect } from '@playwright/test'

const authFile = path.join(process.cwd(), 'playwright/.clerk/user.json')

setup('save Clerk user state', async ({ page }) => {
  await page.goto(process.env.APP_ORIGIN)
  await clerk.signIn({
    page,
    emailAddress: process.env.CLERK_TEST_EMAIL,
  })

  await page.goto(`${process.env.APP_ORIGIN}/account`)
  await expect(page.getByRole('heading', { name: /account/i })).toBeVisible()
  await page.context().storageState({ path: authFile })
})

Add playwright/.clerk/ to .gitignore. The file can contain cookies and headers that grant account access.

The cookies and storage guide explains what Playwright saves and when to seed state manually.

How do you test the real Clerk sign-in UI?

The UI test should use the authentication factors enabled for the application. A password example looks like this:

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

test('customer can sign in through Clerk', async ({ page }) => {
  test.setTimeout(90_000)

  await page.goto(`${process.env.APP_ORIGIN}/sign-in`)
  await expect(page.getByRole('heading', { name: /sign in/i })).toBeVisible()

  await page.getByLabel(/email address/i).fill(process.env.CLERK_TEST_EMAIL)
  await page.getByRole('button', { name: /continue/i }).click()
  await page.getByLabel(/password/i).fill(process.env.CLERK_TEST_PASSWORD)
  await page.getByRole('button', { name: /continue/i }).click()

  await expect(page).toHaveURL(/\/account|\/dashboard/)
  await expect(page.getByTestId('signed-in-user')).toBeVisible()
})

Adapt the flow for email codes, passkeys, or SSO. The clerk.signIn() helper supports password, phone-code, and email-code strategies for development testing, but its client-side strategy handles only the first factor. Clerk recommends server-side email-address sign-in when MFA would otherwise block setup.

What should production monitoring test?

Clerk announced production testing-token support in August 2025. Those tokens allow an automated browser to bypass bot protection on a production instance.

Use production monitoring for a narrow journey:

  1. Load the application and confirm Clerk initializes.
  2. Open the configured sign-in route.
  3. Authenticate a least-privilege monitoring user.
  4. Verify one protected application element.
  5. Sign out or let the isolated browser context close.

Hyperping Browser Checks bundle Playwright but do not bundle @clerk/testing. A script pasted directly into Hyperping should therefore use the customer-facing UI, or reuse an application-controlled session mechanism that does not require that package. Keep helper-based tests in the repository's CI suite.

This distinction prevents a local sample from depending on a package unavailable in the scheduled runtime.

How do you test sign-out?

Clerk's helper can end the current session in CI:

await clerk.signOut({ page })
await page.goto(`${process.env.APP_ORIGIN}/account`)
await expect(page).toHaveURL(/\/sign-in/)

The UI monitor should click the same account-menu action a customer uses, then reopen the protected route and expect a redirect. This catches application logout handlers that fail before Clerk receives the request.

How to use Hyperping for Clerk authentication monitoring

1. Prepare a Clerk test user

Create a least-privilege user reserved for the scheduled check. Keep its password and email in environment variables.

2. Test the customer sign-in page

Record the enabled sign-in strategy with Playwright Codegen, then replace generated selectors with labels and roles.

3. Verify a protected route

Assert a stable application element after authentication. Do not stop at a successful Clerk redirect.

4. Separate helper and UI coverage

Run @clerk/testing helper-based tests in CI. Use a customer-facing Playwright journey for the scheduled production check.

5. Schedule the production check

Create a Hyperping Browser Check, add the test user's credentials as environment variables, and inspect the first run before setting the alert interval.

Use the helper for speed and the UI for confidence

Clerk's helpers reduce repeated authentication work across a test suite. The UI journey verifies the pieces those helpers bypass, including component rendering, factor selection, redirects, and application session creation.

For broader patterns, read the Playwright authentication guide and the guide to tabs, popups, and dialogs for OAuth providers that open a separate window.