feat: Add Testing Tokens docs (#942)

Author: agis

docs/manifest.json

@@ -359,6 +359,7 @@
       ["Test Emails and Phones", "/testing/test-emails-and-phones"],
       "# Testing Frameworks",
       ["Cypress", "/testing/cypress"],
+      ["Playwright", "/testing/playwright"],
       ["Postman or Insomnia", "/testing/postman-or-insomnia"]
     ]
   ],

docs/testing/overview.mdx

@@ -11,6 +11,20 @@ Testing is an important part of every application. Clerk has built some helpers
 
 To avoid sending an email or SMS message with a one time passcode (OTP) during testing, you can use a faux email address or phone number that has a fixed code. Read the complete documentation [here](https://clerk.com/docs/testing/test-emails-and-phones).
 
-## End-to-end (E2E) testing
+## Testing Tokens
 
-Currently, end-to-end testing is not fully supported with Clerk due to tests getting detected as bot traffic. We are currently working on a solution for this.
+Testing Tokens enable bypassing various bot detection mechanisms that typically safeguard Clerk applications against malicious bots, thus allowing test suites to run uninhibited. Without Testing Tokens, you may encounter "Bot traffic detected" errors in your requests.
+
+Obtained via the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Testing-Tokens), Testing Tokens are short-lived and valid only for the specific instance for which they are issued. Testing Tokens are only available in development instances.
+
+Upon retrieval, include the token value in a `__clerk_testing_token` query parameter with your Frontend API requests. For instance, a sign-up request using a Testing Token, would look like this:
+
+```
+POST https://happy-hippo-1.clerk.accounts.dev/v1/sign_ups?__clerk_testing_token=1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy
+```
+
+While manually integrating this logic in your test suite is possible, if you use Playwright you can use our [Playwright integration](/docs/testing/playwright), which will automatically perform all of this for you. We are working on a similar integration for Cypress.
+
+For more information, feedback or issues, visit the
+[`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing)
+package.

docs/testing/playwright.mdx

@@ -0,0 +1,67 @@
+---
+title: Testing with Playwright
+description: Use Playwright to write end-to-end tests with Clerk.
+---
+
+# Testing with Playwright
+
+Playwright is a well-established JavaScript testing framework. This guide aims to help you set up your environment for creating authenticated tests with Clerk. This guide will assume you're somewhat familiar with Clerk and Playwright.
+
+Before diving in, you might want to start by visiting the [Playwright starter](https://github.com/clerk/playwright-clerk-nextjs-example) for an example repo that tests a Clerk-powered application using [Testing Tokens](/docs/testing/overview#testing-tokens).
+
+<Steps>
+### Install `@clerk/testing`
+
+Clerk's testing package provides integration helpers for popular testing frameworks.
+
+```bash filename="terminal"
+npm install @clerk/testing --save-dev
+```
+
+### Set your API keys
+
+Set your publishable and secret keys in your test runner, as the `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` environment variables respectively.
+
+<Callout type="warning">
+  Ensure you provide the secret key in a secure manner, to avoid leaking it to third parties. For example, if you are using GitHub Actions, refer to [*Using secrets in GitHub Actions*](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions).
+</Callout>
+
+### Global setup
+
+In your [global setup file](https://playwright.dev/docs/test-global-setup-teardown), call the `clerkSetup` function:
+
+```tsx filename="global-setup.ts"
+import { clerkSetup } from '@clerk/testing/playwright';
+import { test as setup } from '@playwright/test';
+
+setup('global setup', async ({ }) => {
+  await clerkSetup();
+});
+```
+
+`clerkSetup` will obtain a [Testing Token](/docs/testing/overview#testing-tokens) when your test suite starts, making it available for all subsequent tests to use.
+
+<Callout type="info">
+  You can set the Testing Token yourself as opposed to calling `clerkSetup`, by
+  setting it in the `CLERK_TESTING_TOKEN` environment variable.
+</Callout>
+
+### Use `setupClerkTestingToken`
+
+Then, in your tests use the `setupClerkTestingToken` function to augment your requests with the token:
+
+```tsx filename="my-test.spec.ts"
+import { setupClerkTestingToken } from "@clerk/testing/playwright";
+import { test } from "@playwright/test";
+
+test("sign up", async ({ page }) => {
+  await setupClerkTestingToken({ page });
+
+  await page.goto("/sign-up");
+  // ...
+});
+```
+
+</Steps>
+
+For more information, feedback or issues, visit the [`@clerk/testing`](https://github.com/clerk/javascript/tree/main/packages/testing) package.