clerk-testing

Testing

Documentation

• Testing overview
• Playwright
• Cypress

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

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