clerk-testing

作者： clerk

針對 Clerk 身份驗證流程在 Playwright 與 Cypress 中的端到端測試工具。支援 Playwright 與 Cypress 框架，並提供框架專屬的設定模式（Playwright 的 globalSetup、Cypress 的自訂指令）。提供 clerkSetup() 與 setupClerkTestingToken() 工具，用於初始化測試環境並繞過機器人偵測。包含 storageState 持久化功能，可跨測試重複使用已驗證的工作階段，減少測試執行時間。需要測試 API 金鑰（pk_test_*、...）。

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

下載 ZIP GitHub

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 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`