From e3bbf772e7a625a4b6ae5eb262823c6c59fcffc3 Mon Sep 17 00:00:00 2001
From: Jeff Escalante <jescalan@users.noreply.github.com>
Date: Fri, 20 Dec 2024 16:39:09 -0500
Subject: [PATCH] add a section on testing flow for getting valid session
 tokens (#1829)

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>
---
 docs/testing/overview.mdx | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

diff --git a/docs/testing/overview.mdx b/docs/testing/overview.mdx
index 03e99e2955..4191370e91 100644
--- a/docs/testing/overview.mdx
+++ b/docs/testing/overview.mdx
@@ -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.
@@ -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.