Testing with Playwright
Playwright is an open-source, end-to-end testing framework that automates web application testing across multiple browsers. This guide will help you set up your environment for creating authenticated tests with Clerk, assuming you have some familiarity with both Clerk and Playwright.
Install @clerk/testing
Clerk's testing package provides integration helpers for popular testing frameworks. Run the following command to install it:
npm i @clerk/testing --save-devyarn add -D @clerk/testingpnpm add @clerk/testing -DSet your API keys
In your test runner, set your and as the CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY environment variables, respectively.
Configure Playwright with Clerk
The clerkSetup() function obtains a Testing Token when your test suite starts, making it available for all subsequent tests to use. This ensures that you don't have to manually generate a Testing Token for each test.
To configure Playwright with Clerk, call the clerkSetup() function in your global setup file, as shown in the following example:
import { clerkSetup } from '@clerk/testing/playwright'
import { test as setup } from '@playwright/test'
// Setup must be run serially, this is necessary if Playwright is configured to run fully parallel: https://playwright.dev/docs/test-parallel
setup.describe.configure({ mode: 'serial' })
setup('global setup', async ({}) => {
await clerkSetup()
})Use setupClerkTestingToken()
Now that Playwright is configured with Clerk, you can use the setupClerkTestingToken() function to include the Testing Token in individual test cases. This function injects the Testing Token for the specific test, ensuring the test can bypass Clerk's bot detection mechanisms. See the following example:
import { setupClerkTestingToken } from '@clerk/testing/playwright'
import { test } from '@playwright/test'
test('sign up', async ({ page }) => {
await setupClerkTestingToken({ page })
await page.goto('/sign-up')
// Add additional test logic here
})Troubleshooting
Sign-up form fields missing (e.g., first and last name)
If the <SignUp /> component only renders email and password fields in your Playwright tests but shows all fields in a normal browser, check your Playwright config for the --disable-web-security Chrome launch argument.
This flag strips the Origin header from cross-origin requests, which causes Clerk's API to reject the environment configuration request. Without the environment config, the component falls back to a minimal form.
Remove --disable-web-security from your launchOptions.args to fix this.
setupClerkTestingToken error: "Clerk Frontend API URL is required"
Make sure clerkSetup() is called in a project-based setup, not a function-based globalSetup.
With a function-based globalSetup, the setup runs in a separate process and the environment variables set by clerkSetup() (CLERK_FAPI and CLERK_TESTING_TOKEN) don't propagate to your test workers.
Use a project-based setup as shown in the Configure Playwright with Clerk section above, and declare it as a dependency for your test projects.
Feedback
Last updated on