Skip to content

Commit

Permalink
add a section on testing flow for getting valid session tokens (#1829)
Browse files Browse the repository at this point in the history
Co-authored-by: Alexis Aguilar <[email protected]>
  • Loading branch information
jescalan and alexisintech authored Dec 20, 2024
1 parent 5dacc19 commit e3bbf77
Showing 1 changed file with 16 additions and 3 deletions.
19 changes: 16 additions & 3 deletions docs/testing/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,25 @@ description: Learn about testing with Clerk.

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](/contact/support){{ target: '_blank' }}.

## Testing with one time passcodes
## 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](/docs/testing/test-emails-and-phones).

## 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](https://clerk.com/docs/reference/backend-api/tag/Users#operation/CreateUser).
1. [Create a new session](https://clerk.com/docs/reference/backend-api/tag/Sessions#operation/createSession) for the user.
1. [Create a session token](https://clerk.com/docs/reference/backend-api/tag/Sessions#operation/CreateSessionToken) using the session ID returned in the previous step.
1. 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](/docs/how-clerk-works/overview).

If the session token expires, you will need to refresh it with the same [create session token endpoint](https://clerk.com/docs/reference/backend-api/tag/Sessions#operation/CreateSessionToken). 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`](https://github.com/clerk/javascript/tree/main/packages/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.
Expand All @@ -23,5 +38,3 @@ Once retrieved, include the token value in the `__clerk_testing_token` query par
```shell
POST https://happy-hippo-1.clerk.accounts.dev/v1/client/sign_ups?__clerk_testing_token=1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy
```

For more information, feedback or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package.

0 comments on commit e3bbf77

Please sign in to comment.