Testing

Documentation

Mental Model

Test auth = isolated session state. Each test needs fresh auth context.

clerkSetup() initializes test environment
setupClerkTestingToken() bypasses bot detection
storageState persists auth between tests for speed

Workflow

Identify test framework (Playwright or Cypress)
WebFetch the appropriate documentation link above
Follow official setup instructions
Use development-instance keys only (pk_test_* / sk_test_*). If the project has no keys yet, npx clerk@latest init (the Clerk CLI; see clerk-setup) creates a Clerk application and writes development-instance keys to the env file. No Clerk account or Dashboard visit is needed.

Best Practices

Use setupClerkTestingToken() before navigating to auth pages
Use test API keys: pk_test_xxx, sk_test_xxx
Save auth state with storageState for faster tests
Use page.waitForSelector('[data-clerk-component]') for Clerk UI

Anti-Patterns

Pattern	Problem	Fix
Production keys in tests	Security risk	Use `pk_test_*` keys
No `setupClerkTestingToken()`	Auth fails	Call before navigation
UI-based sign-in every test	Slow tests	Use `storageState`

Framework-Specific

Playwright: Use globalSetup for auth state Cypress: Add to support file

--- name: clerk-testing description: E2E testing for Clerk apps. Use with Playwright or Cypress for auth flow tests. allowed-tools: WebFetch license: MIT metadata: author: clerk version: 1.2.2 compatibility: Requires a publishable key and either CLERK_SECRET_KEY or CLERK_TESTING_TOKEN. Keys can be auto-generated by `clerk init` (temporary development keys, no Clerk account required), or pulled from the Clerk Dashboard. --- # Testing ## Documentation - [Testing overview](https://clerk.com/docs/guides/development/testing/overview) - [Playwright](https://clerk.com/docs/guides/development/testing/playwright/overview) - [Cypress](https://clerk.com/docs/guides/development/testing/cypress/overview) ## Mental Model Test auth = isolated session state. Each test needs fresh auth context. - `clerkSetup()` initializes test environment - `setupClerkTestingToken()` bypasses bot detection - `storageState` persists auth between tests for speed ## Workflow 1. Identify test framework (Playwright or Cypress) 2. WebFetch the appropriate documentation link above 3. Follow official setup instructions 4. Use development-instance keys only (`pk_test_*` / `sk_test_*`). If the project has no keys yet, `npx clerk@latest init` (the Clerk CLI; see `clerk-setup`) creates a Clerk application and writes development-instance keys to the env file. No Clerk account or Dashboard visit is needed. ## Best Practices - Use `setupClerkTestingToken()` before navigating to auth pages - Use test API keys: `pk_test_xxx`, `sk_test_xxx` - Save auth state with `storageState` for faster tests - Use `page.waitForSelector('[data-clerk-component]')` for Clerk UI ## Anti-Patterns | Pattern | Problem | Fix | |---------|---------|-----| | Production keys in tests | Security risk | Use `pk_test_*` keys | | No `setupClerkTestingToken()` | Auth fails | Call before navigation | | UI-based sign-in every test | Slow tests | Use `storageState` | ## Framework-Specific **Playwright**: Use `globalSetup` for auth state **Cypress**: Add `addClerkCommands({ Cypress, cy })` to support file ## See Also - `clerk-setup` - Install Clerk before adding tests - `clerk-nextjs-patterns` - Next.js patterns being tested - [Demo Repo](https://github.com/clerk/clerk-playwright-nextjs/tree/main/e2e)

Clerk Testing

SKILL.md