@clerk/testing

Changelog · Report a Bug · Request a Feature · Ask a Question

Overview

This package provides utilities for testing Clerk applications.

It currently supports the following testing frameworks:

• Playwright, a Node.js library to automate browsers and web pages.

Getting started

Prerequisites

• Node.js >=18.17.0 or later
• Playwright v1+

Installation

npm install @clerk/testing --save-dev

Usage

Playwright

Firstly, add your Clerk keys (CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY) to your environment variables file (e.g. .env.local or .env.). You can find these keys in your Clerk Dashboard.

All Playwright related utilities are exported from @clerk/testing/playwright. Make sure that your import paths are correct!

On your global setup file for Playwright, you must use the clerkSetup function to set up Clerk for your tests.

// global-setup.ts
import { clerkSetup } from '@clerk/testing/playwright';
import { test as setup } from '@playwright/test';

setup('global setup', async ({ }) => {
  await clerkSetup();
  ...
});

Then, you can use the setupClerkTestingToken function to bypass bot protection on your tests.

// 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");
  ...
});

Support

You can get in touch with us in any of the following ways:

• Join our official community Discord server
• Create a GitHub Discussion
• Contact options listed on our Support page

Contributing

We're open to all community contributions! If you'd like to contribute in any way, please read our contribution guidelines.

Security

@clerk/testing follows good practices of security, but 100% security cannot be assured.

@clerk/testing is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.