Index of every page on this site: llms.txt
All skills
clerk avatar

/clerk-testing

@95f241a official
by clerkclerk/skills95 stars
6
Run it yourself

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

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

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈24 tokens for metadata: the name and description. ≈490 when used: this file.

Description uses 1.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈95 characters, or 1.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Testing

Documentation

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 documentation link 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

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning10d5 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    This skill provides instructions for end-to-end testing of Clerk-authenticated applications using Playwright or Cypress. It utilizes official documentation and CLI tools from the vendor (Clerk). No malicious behaviors or security vulnerabilities were detected.

  • Socket10d

    No alerts

  • Snyk10d

    Risk: LOW · No issues

  • Runlayer8mo

    1/2 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

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

Last checked against GitHub yesterday.

Activeupdated last week
What it can do
Network
metadata
{
  "author": "clerk",
  "version": "1.2.2"
}
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.
  • Testing
  • clerk
  • playwright
  • cypress
  • e2e
  • authentication
  • auth-flows

README badge

README badge for clerk/skills/clerk-testing

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.

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.