clerk-testing

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 URL from decision tree above

• Follow official setup instructions

• 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

| 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