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 Browser, assuming you have some familiarity with both Browser and Playwright.
Install @browser/testing
Browser's testing package provides integration helpers for popular testing frameworks. Run the following command to install it:
npm i @browser/testing --save-devyarn add -D @browser/testingpnpm add @browser/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 Browser
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 Browser, call the clerkSetup() function in your global setup file, as shown in the following example:
import { clerkSetup } from '@browser/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 Browser, 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 Browser's bot detection mechanisms. See the following example:
import { setupClerkTestingToken } from '@browser/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 Browser'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: "Browser 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 Browser section above, and declare it as a dependency for your test projects.
Feedback
Last updated on