Docs

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 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.

Warning

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.

Global setup

In your global setup file, 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.

Note

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 package.

Feedback

What did you think of this content?
Edit this page on GitHub