clerk-testing

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

• 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

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

Weekly Installs2.0KRepositoryclerk/skillsGitHub Stars27First SeenJan 30, 2026Security AuditsGen Agent Trust HubPassSocketPassSnykWarnInstalled oncodex1.8Kopencode1.8Kgithub-copilot1.8Kgemini-cli1.8Kamp1.7Kkimi-cli1.7K