playwright

Playwright + Next.js 测试最佳实践

面向 Next.js 应用的 Playwright 综合测试优化指南。包含 8 个类别中的 43 条规则，并按影响程度排序，助你编写可靠、快速且易于维护的端到端测试。

适用场景

在以下场景中可参考这些指南：

• 为 Next.js 应用编写新的 Playwright 测试
• 调试不稳定或失败的测试
• 优化测试执行速度
• 设置身份验证状态复用
• 配置用于测试的 CI/CD 流水线
• 测试 Server Components 和 App Router 功能
• 检查测试代码中的可靠性问题

按优先级划分的规则类别

优先级	类别	影响程度	前缀
1	测试架构	CRITICAL	arch-
2	选择器与定位器	CRITICAL	loc-
3	等待与断言	HIGH	wait-
4	身份验证与状态	HIGH	auth-
5	模拟与网络	MEDIUM-HIGH	mock-
6	Next.js 集成	MEDIUM	next-
7	性能与速度	MEDIUM	perf-
8	调试与 CI	LOW-MEDIUM	debug-

快速参考

1. 测试架构（CRITICAL）

• arch-test-isolation - 为每项测试使用全新的浏览器上下文
• arch-parallel-execution - 启用并行测试执行
• arch-page-object-model - 对复杂页面使用页面对象模型
• arch-fixtures - 使用 fixtures 共享初始化设置
• arch-test-production - 针对生产构建进行测试
• arch-cleanup-state - 每项测试后清理测试状态

2. 选择器与定位器（CRITICAL）

• loc-role-selectors - 优先使用基于角色的选择器，而非 CSS
• loc-data-testid - 对动态元素使用 data-testid
• loc-label-selectors - 对表单输入使用 getByLabel
• loc-text-selectors - 对静态内容使用 getByText
• loc-avoid-xpath - 避免使用 XPath 选择器
• loc-chained-locators - 链式组合定位器以提高精确度
• loc-placeholder-selector - 谨慎使用 getByPlaceholder

3. 等待与断言（HIGH）

• wait-web-first-assertions - 使用 web-first 断言
• wait-avoid-hard-waits - 避免硬性等待
• wait-network-idle - 对复杂页面使用网络空闲状态
• wait-action-retries - 交互前让操作自动等待
• wait-soft-assertions - 对非关键检查使用软断言
• wait-custom-timeout - 合理配置超时时间

4. 身份验证与状态（HIGH）

• auth-storage-state - 使用 storage state 复用身份验证状态
• auth-multiple-roles - 为不同角色使用独立的 storage state
• auth-session-storage - 处理身份验证所需的 session storage
• auth-api-login - 使用 API 登录加快身份验证初始化
• auth-parallel-workers - 为并行测试使用 worker 作用域的身份验证

5. 模拟与网络（中高）

• mock-api-responses - 为确定性测试模拟 API 响应
• mock-intercept-modify - 拦截并修改真实响应
• mock-har-files - 使用 HAR 文件处理复杂的模拟场景
• mock-abort-requests - 中止不必要的请求
• mock-network-conditions - 模拟网络条件

6. Next.js 集成（中）

• next-wait-hydration - 交互前等待水合完成
• next-server-components - 正确测试服务端组件
• next-app-router-navigation - 测试 App Router 导航模式
• next-server-actions - 端到端测试服务端操作
• next-baseurl-config - 配置 baseURL，实现简洁导航

7. 性能与速度（中）

• perf-sharding - 为大型测试套件使用分片
• perf-headless-ci - 在 CI 中使用无头模式
• perf-browser-selection - 有策略地选择浏览器
• perf-reuse-server - 尽可能复用开发服务器
• perf-retries - 配置重试机制，以恢复不稳定的测试

8. 调试与 CI（低至中）

• debug-trace-viewer - 使用跟踪查看器排查失败的测试
• debug-screenshots-videos - 在失败时捕获屏幕截图和视频
• debug-inspector - 使用 Playwright Inspector 进行交互式调试
• debug-ci-reporters - 配置报告器以集成 CI

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	说明
AGENTS.md	包含所有规则的完整汇编指南
references/_sections.md	分类定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息