playwright

Playwright + Next.js 测试最佳实践

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

适用场景

在以下情况下参考这些指南：

• 为 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 - 使用 fixture 共享设置
• 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
• loc-frame-locator - 使用 frameLocator 定位 iframe 内的元素

3. 等待与断言（HIGH）

• wait-web-first-assertions - 使用 Web 优先断言
• assert-aria-snapshots - 使用 aria 快照断言无障碍结构
• 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

使用方法

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect                   # installed vs. targeted versions
npx -y @pymodel/react-frontend-skills scan --skill playwright  # deprecated APIs → rule IDs

对于上述每项与任务匹配的规则，以及每个 scan 命中项，阅读 references/<rule-id>.md，了解其重要性，以及错误与正确的代码示例。