AutoGineer
Generated banner for Clerk Testing
Generated logo for Clerk Testing

Clerk Testing

ClerkOfficialCreated by clerk

  • Skill
  • Tool integration
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

E2E testing for Clerk apps. Use with Playwright or Cypress for auth flow tests.
— the description by clerk

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The clerk-testing skill provides a structured approach to performing end-to-end (E2E) testing for applications integrated with Clerk. It focuses on managing authentication state efficiently, ensuring that tests remain isolated, fast, and secure. By leveraging specific setup functions and configuration patterns, developers can bypass bot detection and maintain consistent auth contexts across test suites.

What it does

  • Provides guidance on setting up E2E tests with Playwright and Cypress.
  • Explains how to manage authentication state to ensure test isolation.
  • Details the use of test-specific API keys for secure development environments.
  • Offers patterns for persisting auth state to improve test execution speed.
  • Outlines methods to bypass bot detection during automated authentication flows.
  • Recommends specific selectors for interacting with Clerk UI components.

When to use it

  • When you need to verify authentication flows in a Clerk-enabled application.
  • When setting up a new testing suite using Playwright or Cypress.
  • When you need to optimize test performance by reusing authenticated sessions.
  • When you need to ensure your test environment is isolated from production data.

Advantages

  • Reduces test execution time by utilizing storage state persistence.
  • Ensures security by enforcing the use of development-instance keys.
  • Provides framework-specific commands for seamless integration.
  • Simplifies the setup process for automated authentication testing.

Usage examples

“How do I set up Clerk authentication testing for my Playwright project?”
The agent will guide you to use the official Playwright documentation link, implement globalSetup for auth state, and ensure you are using development-instance keys.
“My tests are failing because of bot detection during sign-in. How do I fix this?”
The agent will instruct you to call setupClerkTestingToken() before navigating to your authentication pages to bypass bot detection.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/clerk/clerk-testing/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip clerk-testing.zip -d .agents/skills

Documentation by clerk

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

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

Files

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Declares allowed tools, Names Claude Code tools, Needs an API key, Needs Node.js

The author says: 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.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
clerk
Publisher
Clerk (Official)
Source
clerk/skills · skills/clerk-testing · commit c5d2c0d
Licence
MIT License (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by clerk or Clerk.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download clerk-testing.zip