Agent skill
clerk-testing
E2E testing for Clerk apps. Use with Playwright or Cypress for auth flow tests.
Install this agent skill to your Project
npx add-skill https://github.com/clerk/skills/tree/main/skills/testing
Metadata
Additional technical details for this skill
- author
- clerk
- version
- 1.1.0
SKILL.md
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 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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
clerk/skills
clerk-backend-api
Clerk backend REST API
clerk/skills
clerk
Clerk authentication router. Use when user asks about adding authentication, setting up Clerk, custom sign-in flows, Swift or native iOS auth, native Android auth, Next.js patterns, organizations, syncing users, or testing. Automatically routes to the specific skill based on their task.
clerk/skills
clerk-webhooks
Clerk webhooks for real-time events and data syncing. Listen for user creation, updates, deletion, and organization events. Build event-driven features like database sync, notifications, integrations.
clerk/skills
clerk-android
Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.
clerk/skills
clerk-setup
Add Clerk authentication to any project by following the official quickstart guides.
clerk/skills
clerk-nextjs-patterns
Advanced Next.js patterns - middleware, Server Actions, caching with Clerk.
Didn't find tool you were looking for?