clerk-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

测试框架	文档链接
概述	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

测试认证 = 独立会话状态。每个测试都需要全新的认证上下文。

```
clerkSetup()
```
初始化测试环境
```
setupClerkTestingToken()
```
绕过机器人检测
```
storageState
```
在测试间持久化认证信息以提升测试速度

Workflow

工作流程

Identify test framework (Playwright or Cypress)
WebFetch the appropriate URL from decision tree above
Follow official setup instructions
Use
```
pk_test_*
```
and
```
sk_test_*
```
keys only

确定测试框架（Playwright或Cypress）
从上方决策树中获取对应的URL
遵循官方设置指南
仅使用
```
pk_test_*
```
和
```
sk_test_*
```
密钥

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

在导航到认证页面之前使用
```
setupClerkTestingToken()
```
使用测试API密钥：
```
pk_test_xxx
```
,
```
sk_test_xxx
```
使用
```
storageState
```
保存认证状态以加快测试速度

针对Clerk UI使用

page.waitForSelector('[data-clerk-component]')

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`

不良模式	问题	解决方案
测试中使用生产密钥	安全风险	使用 `pk_test_*` 密钥
未使用 `setupClerkTestingToken()`	认证失败	导航前调用该函数
每次测试都基于UI登录	测试速度慢	使用 `storageState`

Framework-Specific

框架专属配置

Playwright: Use

globalSetup

for auth state Cypress: Add

addClerkCommands({ Cypress, cy })

to support file

Playwright：使用

globalSetup

管理认证状态 Cypress：在支持文件中添加

addClerkCommands({ Cypress, cy })