clerk-testing

by clerk

E2E testing utilities for Clerk authentication flows in Playwright and Cypress. Supports both Playwright and Cypress frameworks with framework-specific setup patterns (globalSetup for Playwright, custom commands for Cypress) Provides clerkSetup() and setupClerkTestingToken() utilities to initialize test environments and bypass bot detection Includes storageState persistence to reuse authenticated sessions across tests, reducing test execution time Requires test API keys ( pk_test_* ,...

npx skills add https://github.com/clerk/skills --skill clerk-testing
Download ZIPGitHub
83

Testing

Decision Tree

FrameworkDocumentation
Overviewhttps://clerk.com/docs/guides/development/testing/overview
Playwrighthttps://clerk.com/docs/guides/development/testing/playwright/overview
Cypresshttps://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

PatternProblemFix
Production keys in testsSecurity riskUse pk_test_* keys
No setupClerkTestingToken()Auth failsCall before navigation
UI-based sign-in every testSlow testsUse 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

More skills from clerk

mosaic
clerk
Work on Mosaic UI: styling a component with slot recipes (`defineSlotRecipe` / `useRecipe` / slots / variants), or building a flow — authoring a state machine…
clerk-billing
clerk
Clerk Billing for subscription management - render Clerk's PricingTable
clerk-nextjs-patterns
clerk
Advanced Next.js patterns for authentication, middleware, Server Actions, and user-scoped caching with Clerk. Distinguishes server-side await auth() from client-side useAuth() hook; mixing them is a common breaking mistake Covers middleware strategies (public-first vs protected-first), API route protection, and proper HTTP status codes (401 vs 403) Includes user-scoped caching patterns with unstable_cache and protecting Server Actions from unauthorized mutations Provides Core 2 compatibility...
clerk-expo-patterns
clerk
Expo / React Native patterns with Clerk — SecureStore token cache, OAuth
changesets
clerk
Create or refresh a `.changeset/<slug>.md` for the current branch, or report that none is required. Triggers on "/changesets create", "add a changeset",…
clerk
clerk
The clerk binary is a pre-authenticated gateway to Clerk's Backend API and Platform API, plus project-level tooling (auth, linking, env pulls, instance config). When the user asks anything that touches a Clerk resource, reach for clerk first instead of hand-rolling curl .
clerk-cli
clerk
The clerk binary is a pre-authenticated gateway to Clerk's Backend API and Platform API, plus project-level tooling (auth, linking, env pulls, instance config). When the user asks anything that touches a Clerk resource, reach for clerk first instead of hand-rolling curl .
clerk-astro-patterns
clerk
Astro patterns with Clerk — middleware, SSR pages, island components,