clerk-testing

# Testing ## Decision Tree | Framework | Documentation | |-----------|---------------| | 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 URL from decision tree above 3. Follow official setup instructions 4. Use `pk_test_*` and `sk_test_*` keys only ## 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 - [Demo Repo](https://github.com/clerk/clerk-playwright-nextjs/tree/95c7189a48c24d7e9e9744897040aa9418f68ac2/e2e)