Playwright 最佳实践

本技能为 Playwright 测试开发的各个方面提供全面指导，从编写新测试到调试和维护现有测试套件。

基于活动的参考指南

根据您正在执行的操作查阅这些参考资料：

编写新测试

何时使用：创建新的测试文件、编写测试用例、实现测试场景

移动与响应式测试

何时使用：测试移动设备、触摸交互、响应式布局

实时与浏览器 API

何时使用：测试 WebSocket、地理位置、权限、多标签页流程

调试与故障排除

何时使用：测试失败、元素未找到、超时、意外行为

错误与边缘情况测试

何时使用：测试错误状态、离线模式、网络故障、验证

多用户与协作测试

何时使用：测试涉及多用户、角色或实时协作的功能

重构与维护

何时使用：改进现有测试、代码审查、减少重复

基础设施与配置

何时使用：设置项目、配置 CI/CD、优化性能

高级模式

何时使用：复杂场景、API 模拟、网络拦截

快速决策树

你在做什么？
│
├─ 编写新测试？
│  ├─ 端到端测试 → test-organization.md, locators.md, assertions-waiting.md
│  ├─ 组件测试 → component-testing.md
│  ├─ API 测试 → test-organization.md, assertions-waiting.md
│  ├─ 视觉/Canvas 测试 → canvas-webgl.md, test-organization.md
│  ├─ 可访问性测试 → accessibility.md
│  ├─ 移动/响应式测试 → mobile-testing.md
│  ├─ i18n/本地化测试 → i18n.md
│  ├─ Electron 应用测试 → electron.md
│  ├─ 浏览器扩展测试 → browser-extensions.md
│  └─ 多用户测试 → multi-user.md
│
├─ 测试特定功能？
│  ├─ 文件上传/下载 → file-operations.md
│  ├─ 日期/时间依赖 → clock-mocking.md
│  ├─ WebSocket/实时 → websockets.md
│  ├─ 地理位置/权限 → browser-apis.md
│  ├─ OAuth/SSO 模拟 → third-party.md, multi-context.md
│  ├─ 支付/邮件/SMS → third-party.md
│  ├─ iFrame → iframes.md
│  ├─ Canvas/WebGL/图表 → canvas-webgl.md
│  ├─ Service Workers/PWA → service-workers.md
│  ├─ i18n/本地化 → i18n.md
│  ├─ 安全 (XSS, CSRF) → security-testing.md
│  └─ 性能/Web Vitals → performance-testing.md
│
├─ 测试失败/不稳定？
│  ├─ 不稳定测试调查 → flaky-tests.md
│  ├─ 元素未找到 → locators.md, debugging.md
│  ├─ 超时问题 → assertions-waiting.md, debugging.md
│  ├─ 竞态条件 → flaky-tests.md, debugging.md
│  ├─ 仅当有多个工作进程时不稳 → flaky-tests.md, performance.md
│  ├─ 状态泄漏 / 隔离问题 → flaky-tests.md, fixtures-hooks.md
│  ├─ 控制台/JS 错误 → console-errors.md, debugging.md
│  └─ 一般调试 → debugging.md
│
├─ 测试错误场景？
│  ├─ 网络故障 → error-testing.md, network-advanced.md
│  ├─ 离线（意外情况） → error-testing.md
│  ├─ 离线优先/PWA → service-workers.md
│  ├─ 错误边界 → error-testing.md
│  └─ 表单验证 → error-testing.md
│
├─ 重构现有代码？
│  ├─ 实施页面对象模型 → page-object-model.md
│  ├─ 改进选择器 → locators.md
│  ├─ 提取固件 → fixtures-hooks.md
│  └─ 创建数据工厂 → test-data.md
│
├─ 设置基础设施？
│  ├─ CI/CD → ci-cd.md
│  ├─ 全局设置/清理 → global-setup.md
│  ├─ 项目依赖 → projects-dependencies.md
│  ├─ 测试性能 → performance.md
│  ├─ 测试覆盖率 → test-coverage.md
│  └─ 项目配置 → test-organization.md, projects-dependencies.md
│
└─ 组织测试？
   ├─ 跳过/待修复/慢速测试 → annotations.md
   ├─ 测试步骤 → annotations.md
   └─ 条件执行 → annotations.md

测试验证循环

编写或修改测试后：

1. 运行测试：npx playwright test --reporter=list
2. 如果测试失败：
   • 查看错误输出和跟踪（npx playwright show-trace）
   • 修复选择器、等待或断言
   • 重新运行测试
3. 只有当所有测试通过时才继续
4. 对关键测试多次运行：npx playwright test --repeat-each=5