Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add a section on testing flow for getting valid session tokens #1829

Merged
merged 4 commits into from
Dec 20, 2024
Merged

add a section on testing flow for getting valid session tokens #1829

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c456dc4
add a section on testing flow for getting valid session tokens
jescalan Dec 19, 2024
867a9c1
format
jescalan Dec 19, 2024
0fa949f
fix link
jescalan Dec 20, 2024
960d05d
docs review
alexisintech Dec 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 16 additions & 3 deletions docs/testing/overview.mdx
View file
Open in desktop
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.
Loading