Clerk 身份验证测试指南：Playwright 与 Cypress 集成最佳实践

clerk-testing by clerk/skills

2,300 周安装量

30 GitHub Stars

GitHub

安装命令

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

开发开发运维

🇨🇳中文介绍

测试

决策树

框架	文档
概述	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

心智模型

测试身份验证 = 隔离的会话状态。每个测试都需要全新的身份验证上下文。

clerkSetup() 初始化测试环境
setupClerkTestingToken() 绕过机器人检测
storageState 在测试之间持久化身份验证状态以提升速度

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

705,000 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

245,300 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

196,800 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

128,699 周安装

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

在导航到身份验证页面之前使用 setupClerkTestingToken()
使用测试 API 密钥：pk_test_xxx, sk_test_xxx
使用 storageState 保存身份验证状态以加速测试
使用 page.waitForSelector('[data-clerk-component]') 等待 Clerk UI

模式	问题	修复方法
在测试中使用生产密钥	安全风险	使用 `pk_test_*` 密钥
未使用 `setupClerkTestingToken()`	身份验证失败	在导航前调用
每次测试都基于 UI 登录	测试缓慢	使用 `storageState`

Playwright : 使用 globalSetup 来管理身份验证状态 Cypress : 在支持文件中添加 addClerkCommands({ Cypress, cy })

🇺🇸English

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 pk_test_* and sk_test_* keys only

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

Clerk 身份验证测试指南：Playwright 与 Cypress 集成最佳实践

🇨🇳中文介绍

测试

决策树

心智模型

相关 Skills

工作流程

最佳实践

反面模式

框架特定说明

另请参阅