Testing with Cypress
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.
Install @clerk/testing
Clerk's testing package provides integration helpers for popular testing frameworks. Install it by running the following command:
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.
Global setup
To set up Clerk with Cypress, you must call the clerkSetup()
function in your cypress.config.ts
file.
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:
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.
cy.clerkSignIn
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.
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.
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.
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.
For more information, feedback or issues, visit the @clerk/testing
package.
Feedback
Last updated on