Install @clerk/testing
Set your API keys
Global setup
Use Clerk Testing Tokens
Custom Commands

Testing with Cypress

Warning

Our @clerk/testing package only supports end-to-end testing. Unit tests are not supported.

Testing with Cypress requires the use of Clerk's Testing Tokens to bypass various bot detection mechanisms that typically safeguard Clerk applications against malicious bots. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests.

This guide aims to help you set up your environment for creating Clerk-authenticated tests with Cypress.

Note

Check out the demo repo that tests a Clerk-powered application using Testing Tokens.

Install `@clerk/testing`

Clerk's testing package provides integration helpers for popular testing frameworks. Install it by running the following command:

npm

yarn

pnpm

terminal

npm i @clerk/testing --save-dev

terminal

yarn add -D @clerk/testing

terminal

pnpm add @clerk/testing -D

Set your API keys

In your test runner, set your publishable and secret key as the CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY environment variables, respectively.

To find your keys:

Navigate to the Clerk Dashboard.
In the navigation sidebar, select API Keys.
In the Quick Copy section, copy your Clerk publishable and secret key.

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

To set up Clerk with Cypress, add the following code to your cypress.config.ts file.

cypress.config.ts

import { clerkSetup } from '@clerk/testing/cypress'
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      return clerkSetup({ config })
    },
    baseUrl: 'http://localhost:3000', // your app's URL
  },
})

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

Use Clerk Testing Tokens

Now that Cypress is configured with Clerk, you can use the setupClerkTestingToken() function in your tests to augment them with the Testing Token. See the following example:

my-test.cy.ts

import { setupClerkTestingToken } from '@clerk/testing/cypress'

it('sign up', () => {
  setupClerkTestingToken()

  cy.visit('/sign-up')
  // ...
})

Custom Commands

The @clerk/testing package also provides Cypress custom commands to sign in/sign out with Clerk in your Cypress tests without having to interact with the UI. To use these commands, you must import them in your Cypress E2E support file, as shown in the following example.

cypress/support/e2e.ts

/// <reference types="cypress" />
import { addClerkCommands } from '@clerk/testing/cypress'
addClerkCommands({ Cypress, cy })

export {}

The cy.clerkSignIn command is used to sign in a user using Clerk. This custom command supports only the following first factor strategies:

Password
Phone code
Email code

Multi-factor authentication is not supported.

Note

This helper internally uses the setupClerkTestingToken() helper, so you don't need to call it separately.

Prerequisites

Before calling this command, you must call cy.visit.
Before using this command, navigate to a non-protected page that loads Clerk.

Parameters

cy.clerkSignIn accepts an object with the following properties:

Name
strategy
Type
'password' | 'phone_code' | 'email_code'
Description
The sign-in strategy. Supported strategies are:
password: The command will sign in the user using the provided password and identifier.
phone_code: You must have a user with a test phone number as an identifier (e.g., +15555550100).
email_code: You must have a user with a test email as an identifier (e.g., your_email+clerk_test@example.com).
Name
identifier
Type
string
Description
The user's identifier. This could be a username, a phone number, or an email.
Name
password
Type
string
Description
The user's password. This is required only if the strategy is set to 'password'.

Example

The following example demonstrates how to use the cy.clerkSignIn() command in a test to sign in a user.

cypress/e2e/my-test.cy.ts

it('sign in', () => {
  cy.visit(`/`)
  cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' })
  cy.visit('/protected')
  // user is signed in from here on
})

`cy.clerkSignOut`

The cy.clerkSignOut command is used to sign out the current user using Clerk.

Prerequisites

Before calling this command, yu must call cy.visit.
Before using this command, navigate to a page that loads Clerk.

Parameters

cy.clerkSignOut accepts an optional parameter signOutOptions, which includes the following properties:

Name
sessionId?
Type
string
Description
The ID of a specific session to sign out of. Useful for multi-session applications.
Name
redirectUrl?
Type
string
Description
The redirect URL to navigate to after sign out is complete.

Example

The following example demonstrates how to use the cy.clerkSignOut() command in a test to sign a user out.

cypress/e2e/my-test.cy.ts

it('sign out', () => {
  cy.visit(`/`)
  cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' })
  cy.visit('/protected')
  cy.clerkSignOut()
  // user is signed out from here on
})

`cy.clerkLoaded`

The cy.clerkLoaded command asserts that Clerk has been loaded.

Prerequisites

Before calling this command, you must call cy.visit.
Before using this command, navigate to a page that loads Clerk.

Example

The following example demonstrates how to use the cy.clerkLoaded() command in a test to assert that Clerk has been loaded.

cypress/e2e/my-test.cy.ts

it('check Clerk loaded', () => {
  cy.visit(`/`)
  cy.clerkLoaded()
  // Clerk has been loaded from here on
})

For more information, feedback or issues, visit the @clerk/testing package.

Edit this page on GitHub

Testing with Cypress

Feedback