Docs

Testing

Testing is an important part of every application. Each framework may require a slightly different setup. If you're having trouble getting testing to work properly, contact support.

Test with one time passcodes

To avoid sending an email or SMS message with a one time passcode (OTP) during testing, you can use a fake email address or phone number that has a fixed code. Read the complete documentation here.

Get a valid session token

When writing tests using Clerk, if you need to get a valid session token, use the following flow:

  1. If you have not already, create a new user.
  2. Create a new session for the user.
  3. Create a session token using the session ID returned in the previous step.
  4. Pass the returned session token as the value of an Authorization header to any other requests you're making, as such: Authorization: Bearer <session_token>.

Note that Clerk's session tokens are short-lived and are valid only for 60 seconds. Read more here.

If the session token expires, you will need to refresh it with the same create session token endpoint. The most common ways to do this are to either hit this endpoint before every test to ensure you have a valid session token, or to run an interval timer that refreshes the token before it expires.

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

Testing Tokens

Testing Tokens allow you to bypass bot detection mechanisms that protect Clerk applications from malicious bots, ensuring your test suites run smoothly. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests.

Note

While you can manually implement the following logic in your test suite, Clerk provides Playwright and Cypress integrations that handle this automatically.

Obtained via the Backend API, Testing Tokens are short-lived and valid only for the specific instance for which they are issued.

Once retrieved, include the token value in the __clerk_testing_token query parameter in your Frontend API requests. For example, a sign-up request using a Testing Token would look like this:

POST https://happy-hippo-1.clerk.accounts.dev/v1/client/sign_ups?__clerk_testing_token=1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy

Feedback

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

Last updated on