⚡

Playwright测试最佳实践Skill playwright

本技能专注于使用Playwright进行Next.js应用的端到端测试，提供全面的最佳实践指南，涵盖测试架构、选择器与定位器、等待与断言、身份验证与状态管理、模拟与网络、Next.js集成、性能优化以及调试与CI配置。旨在帮助开发者编写可靠、快速和可维护的测试，提高测试效率和质量。关键词：Playwright, Next.js, 端到端测试, 自动化测试, 测试最佳实践, E2E测试, 测试优化, 软件测试, 前端测试。

测试 0 次安装 0 次浏览更新于 3/18/2026

name: playwright description: Playwright测试针对Next.js应用程序的最佳实践（原test-playwright）。此技能应在编写、审查或调试使用Playwright的端到端测试时使用。触发任务包括测试选择器、不稳定测试、身份验证状态、API模拟、水合测试、并行执行、CI配置或调试测试失败。

Playwright + Next.js 测试最佳实践

Playwright与Next.js应用程序的综合测试优化指南。包含43条规则，分为8个类别，按影响优先级排序，指导可靠、快速和可维护的端到端测试。

何时应用

参考这些指南当：

为Next.js应用编写新的Playwright测试
调试不稳定或失败的测试
优化测试执行速度
设置身份验证状态重用
配置CI/CD管道进行测试
测试服务器组件和App Router功能
审查测试代码的可靠性问题

规则类别按优先级排序

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

快速参考

1. 测试架构（关键）

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

2. 选择器与定位器（关键）

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. 等待与断言（高）

wait-web-first-assertions - 使用Web优先断言
wait-avoid-hard-waits - 避免硬等待
wait-network-idle - 对复杂页面使用网络空闲等待
wait-action-retries - 让操作在交互前自动等待
wait-soft-assertions - 对非关键检查使用软断言
wait-custom-timeout - 适当配置超时

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

auth-storage-state - 使用存储状态重用身份验证
auth-multiple-roles - 对不同角色使用单独的存储状态
auth-session-storage - 处理会话存储以进行身份验证
auth-api-login - 使用API登录以加快身份验证设置
auth-parallel-workers - 对并行测试使用工作域范围的身份验证

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检查器进行交互式调试
debug-ci-reporters - 为CI集成配置报告器

如何使用

阅读单独的参考文件以获取详细解释和代码示例：

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

参考文件

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