Testing with Playwright

Playwright is a well-established JavaScript testing framework. This guide aims to help you set up your environment for creating authenticated tests with Clerk. This guide will assume you're somewhat familiar with Clerk and Playwright.

Before diving in, you might want to start by visiting the Playwright starter(opens in a new tab) for an example repo that tests a Clerk-powered application using Testing Tokens.

Install `@clerk/testing`

Clerk's testing package provides integration helpers for popular testing frameworks.

terminal
npm install @clerk/testing --save-dev

Set your API keys

Set your publishable and secret keys in your test runner, as the CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY environment variables respectively.

Ensure you provide the secret key in a secure manner, to avoid leaking it to third parties. For example, if you are using GitHub Actions, refer to Using secrets in GitHub Actions(opens in a new tab).

Global setup

In your global setup file(opens in a new tab), call the clerkSetup function:

global-setup.ts
import { clerkSetup } from '@clerk/testing/playwright';
import { test as setup } from '@playwright/test';
 
setup('global setup', async ({ }) => {
  await clerkSetup();
});

clerkSetup will obtain a Testing Token when your test suite starts, making it available for all subsequent tests to use.

You can set the Testing Token yourself as opposed to calling clerkSetup, by setting it in the CLERK_TESTING_TOKEN environment variable.

Use `setupClerkTestingToken`

Then, in your tests use the setupClerkTestingToken function to augment your requests with the token:

my-test.spec.ts
import { setupClerkTestingToken } from "@clerk/testing/playwright";
import { test } from "@playwright/test";
 
test("sign up", async ({ page }) => {
  await setupClerkTestingToken({ page });
 
  await page.goto("/sign-up");
  // ...
});

For more information, feedback or issues, visit the @clerk/testing(opens in a new tab) package.

Install @clerk/testing

Set your API keys

Global setup

Use setupClerkTestingToken

Install `@clerk/testing`

Use `setupClerkTestingToken`