clerk-testing
Utilitaires de test E2E pour les flux d'authentification Clerk dans Playwright et Cypress. Prend en charge les frameworks Playwright et Cypress avec des modèles de configuration spécifiques (globalSetup pour Playwright, commandes personnalisées pour Cypress). Fournit les utilitaires clerkSetup() et setupClerkTestingToken() pour initialiser les environnements de test et contourner la détection de bots. Inclut la persistance storageState pour réutiliser les sessions authentifiées entre les tests, réduisant ainsi le temps d'exécution des tests. Nécessite des clés API de test ( 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