skilld
All skills
clerk avatar

/clerk-testing

@4ad201b official
by clerkclerk/skills83 stars
5

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

Ask your Agent

Use this Skill: https://skilld.dev/gh/clerk/skills/clerk-testing

This session only. Nothing lands on disk.

SKILL.md

≈24 tokens always: the name and description. ≈476 when used: this file.

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

Source: SKILL.md on GitHub

Third-party checks

1 warning16d5 checks · Risk SAFE
  • Gen Agent Trust Hub16d

    This skill provides instructions for setting up end-to-end testing for Clerk applications. It references official documentation and follows security best practices for secret management by advising the use of development-instance keys.

  • Socket16d

    No alerts

  • Snyk16d

    Risk: LOW · No issues

  • Runlayer7mo

    1/2 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 4ad201b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 4 weeks ago

Capability

What it can do
Network
metadata
{
  "author": "clerk",
  "version": "1.2.1"
}
All 1 allowed tools
WebFetch
Other metadata
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.

Topics

  • Testing
  • clerk
  • playwright
  • cypress
  • e2e
  • authentication
  • auth-flows

README badge

README badge for clerk/skills/clerk-testing

What it does

Configures Playwright or Cypress for testing Clerk authentication flows using test API keys and session state management. Use this when writing E2E tests for apps with Clerk login, sign-up, and protected routes.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with both Playwright and Cypress?
Yes. The skill covers both frameworks with separate documentation and setup instructions for each. Framework-specific guidance includes using `globalSetup` for Playwright auth state and `addClerkCommands` for Cypress.
What keys should I use for testing?
Use test API keys prefixed with `pk_test_*` and `sk_test_*` from your Clerk dashboard. Never use production keys in tests.
How do I speed up auth tests?
Use `storageState` to persist auth between tests instead of signing in via UI for every test. Call `setupClerkTestingToken()` before navigating to auth pages to bypass bot detection.
What does this skill assume about my setup?
This skill assumes Clerk is already installed in your app. It focuses on E2E testing workflows for auth flows and requires a `CLERK_TESTING_TOKEN` from your Clerk dashboard.

Generated from the current SKILL.md. These answers refresh after source changes.