mcpbeat

Clerk Testing

clerk/clerk-testing

E2E testing for Clerk apps. Use with Playwright or Cypress for auth flow tests.

This is a copy. The original lives at clerk/stripe-webhooks-example-clerk-testing.

482 tokens
context cost
the whole folder, loaded on every use
1
files
instructions only
0
copies elsewhere
how many repositories repackaged it
66
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/clerk/skills --skill clerk-testing

What it tells the agent to use

found in the instruction text
WebFetch fetches pages from the network

The instruction itself

8 sections, as written by the author

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

  • clerk-setup - Install Clerk before adding tests
  • clerk-nextjs-patterns - Next.js patterns being tested
  • Demo Repo

How to use it

Copy the folder

Take clerk/clerk-testing from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.