clerk-testing
Utilidades de pruebas E2E para flujos de autenticación de Clerk en Playwright y Cypress. Compatible con ambos frameworks Playwright y Cypress con patrones de configuración específicos para cada framework (globalSetup para Playwright, comandos personalizados para Cypress). Proporciona las utilidades clerkSetup() y setupClerkTestingToken() para inicializar entornos de prueba y evitar la detección de bots. Incluye persistencia de storageState para reutilizar sesiones autenticadas entre pruebas, reduciendo el tiempo de ejecución. Requiere claves de API de prueba ( pk_test_* ,...
npx skills add https://github.com/clerk/skills --skill clerk-testingTesting
Decision Tree
Mental Model
Test auth = isolated session state. Each test needs fresh auth context.
clerkSetup()initializes test environmentsetupClerkTestingToken()bypasses bot detectionstorageStatepersists 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_*andsk_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
storageStatefor 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 testsclerk-nextjs-patterns- Next.js patterns being tested- Demo Repo