clerk-testing

Clerk 인증 흐름을 위한 Playwright 및 Cypress E2E 테스트 유틸리티입니다. Playwright와 Cypress 프레임워크를 모두 지원하며, 각 프레임워크에 맞는 설정 패턴(Playwright의 globalSetup, Cypress의 커스텀 명령어)을 제공합니다. 테스트 환경을 초기화하고 봇 탐지를 우회하기 위해 clerkSetup()과 setupClerkTestingToken() 유틸리티를 제공합니다. 인증된 세션을 테스트 간에 재사용하여 테스트 실행 시간을 줄이는 storageState 지속성을 포함합니다. 테스트 API 키(pk_test_* ,...)가 필요합니다.

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`

Framework-Specific

Playwright: Use globalSetup for auth state Cypress: Add addClerkCommands({ Cypress, cy }) to support file