clerk-testing — Claude Code skill: Clerk E2E auth tests
Walks an agent through Clerk sign-in tests in Playwright or Cypress, and keeps test keys out of the production config.
npx skills add clerk/skills --skill clerk-testing -a claude-codeWhat clerk-testing does
The skill walks an agent through E2E auth setup for Clerk in Playwright or Cypress. It ships a decision tree of links to the official guides plus rules the agent applies: clerkSetup() to initialize the test environment, setupClerkTestingToken() to get past bot detection, storageState to reuse a session instead of signing in on every test.
Its only tool is WebFetch. The agent opens the matching doc page and follows the steps there rather than reciting them from memory. You supply the test keys: pk_test_* and sk_test_*. No keys in the project yet? npx clerk@latest init creates the Clerk app and writes development keys to your env file, no account needed.
Production keys in a test suite are a security hole, and the skill flags that. Check the env before the first run, because without keys the suite fails at startup.
What it helps with
- stand up Playwright login tests from scratch
- reuse a signed-in session with
storageState - get past bot detection on the sign-in page
- swap production keys for
pk_test_*in the test config - wait for the Clerk widget before asserting
Example prompts for the agent
- Set up Clerk E2E tests in Playwright. The project has no keys, start with
npx clerk@latest init - My Cypress login tests fail: add
setupClerkTestingToken()and wireaddClerkCommandsinto the support file - Rewrite the login step to use
storageStateso we stop signing in for every spec
How to install clerk-testing
1Skills CLI (Vercel)
npx skills add clerk/skills --skill clerk-testing -a claude-code2Manually: put the files in place
~/.claude/skills/clerk-testing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/clerk-testing/
1Skills CLI (Vercel)
npx skills add clerk/skills --skill clerk-testing -a codex2Manually: put the files in place
.agents/skills/clerk-testing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add clerk/skills --skill clerk-testing -a cursor2Manually: put the files in place
.cursor/skills/clerk-testing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install clerk/skills clerk-testing2Manually: put the files in place
.github/skills/clerk-testing/SKILL.md1Skills CLI (Vercel)
npx skills add clerk/skills --skill clerk-testing -a gemini-cli2Platform CLI
gemini skills install https://github.com/clerk/skills --path skills/clerk-testingManually: put the files in place
.devin/skills/clerk-testing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add clerk/skills --skill clerk-testing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about clerk-testing
How do I install clerk-testing in Claude Code?
Run npx skills add clerk/skills --skill clerk-testing -a claude-code. The skill file lands at ~/.claude/skills/clerk-testing/SKILL.md.
What does clerk-testing do?
It guides an agent through Clerk auth tests in Playwright or Cypress: it fetches the official guide, then applies rules on test keys and session reuse.
What do I need before running it?
A publishable key plus CLERK_SECRET_KEY or CLERK_TESTING_TOKEN. Without keys, npx clerk@latest init creates the app and writes development keys to your env file.
Source text
SKILL.md · MIT
---
name: clerk-testing
description: E2E testing for Clerk apps. Use with Playwright or Cypress for auth flow
tests.
allowed-tools: WebFetch
license: MIT
metadata:
author: clerk
version: 1.2.1
compatibility: Requires a publishable key and either CLERK_SECRET_KEY or CLERK_TESTING_TOKEN. Keys can be auto-generated by `clerk init` (temporary development keys, no Clerk account required), or pulled from the Clerk Dashboard.
---
# 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
1. Identify test framework (Playwright or Cypress)
2. WebFetch the appropriate URL from decision tree above
3. Follow official setup instructions
4. Use development-instance keys only (`pk_test_*` / `sk_test_*`). If the project has no keys yet, `npx clerk@latest init` (the Clerk CLI; see `clerk-setup`) creates a Clerk application and writes development-instance keys to the env file. No Clerk account or Dashboard visit is needed.
## 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
- `clerk-setup` - Install Clerk before adding tests
- `clerk-nextjs-patterns` - Next.js patterns being tested
- [Demo Repo](https://github.com/clerk/clerk-playwright-nextjs/tree/main/e2e)
© clerk · MIT · clerk/skills
