playwright-best-practices

Playwright 最佳实践

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

基于活动的参考指南

根据您正在进行的活动查阅以下参考：

编写新测试

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

活动	参考文件
编写端到端测试	test-suite-structure.md, locators.md, assertions-waiting.md
编写组件测试	component-testing.md, test-suite-structure.md
编写API测试	api-testing.md, test-suite-structure.md
编写GraphQL测试	graphql-testing.md, api-testing.md
编写视觉回归测试	visual-regression.md, canvas-webgl.md
使用POM组织测试代码	page-object-model.md, test-suite-structure.md
设置测试数据/夹具	fixtures-hooks.md, test-data.md
处理身份验证	authentication.md, authentication-flows.md
测试日期/时间功能	clock-mocking.md
测试文件上传/下载	file-operations.md, file-upload-download.md
测试表单/验证	forms-validation.md
测试拖放	drag-drop.md
测试可访问性	accessibility.md
测试安全性（XSS、CSRF）	security-testing.md
使用测试注解	annotations.md
使用测试标签	test-tags.md
测试iframe	iframes.md
测试Canvas/WebGL	canvas-webgl.md
国际化（i18n）	i18n.md
测试Electron应用	electron.md
测试浏览器扩展	browser-extensions.md

移动端与响应式测试

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

活动	参考文件
设备模拟	mobile-testing.md
触摸手势（滑动、点击）	mobile-testing.md
视口/断点测试	mobile-testing.md
移动端特定UI	mobile-testing.md, locators.md

实时与浏览器API

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

活动	参考文件
WebSocket/实时测试	websockets.md
地理位置模拟	browser-apis.md
权限处理	browser-apis.md
剪贴板测试	browser-apis.md
摄像头/麦克风模拟	browser-apis.md
多标签页/弹出窗口流程	multi-context.md
OAuth弹出窗口处理	third-party.md, multi-context.md

调试与故障排除

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

活动	参考文件
调试测试失败	debugging.md, assertions-waiting.md
修复不稳定测试	flaky-tests.md, debugging.md, assertions-waiting.md
调试不稳定的并行运行	flaky-tests.md, performance.md, fixtures-hooks.md
确保测试隔离/避免状态泄漏	flaky-tests.md, fixtures-hooks.md, performance.md
修复选择器问题	locators.md, debugging.md
调查超时问题	assertions-waiting.md, debugging.md
使用追踪查看器	debugging.md
调试竞态条件	flaky-tests.md, debugging.md, assertions-waiting.md
调试控制台/JS错误	console-errors.md, debugging.md

错误与边缘情况测试

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

活动	参考文件
错误边界测试	error-testing.md
网络故障模拟	error-testing.md, network-advanced.md
离线模式测试	error-testing.md, service-workers.md
Service Worker测试	service-workers.md
加载状态测试	error-testing.md
表单验证测试	error-testing.md

多用户与协作测试

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

活动	参考文件
单个测试中的多个用户	multi-user.md
实时协作	multi-user.md, websockets.md
基于角色的访问测试	multi-user.md
并发操作测试	multi-user.md

架构决策

何时使用：选择测试模式、决定方法、规划测试架构

活动	参考文件
POM与夹具决策	pom-vs-fixtures.md
测试类型选择	test-architecture.md
模拟与实际服务	when-to-mock.md
测试套件结构	test-suite-structure.md

框架特定测试

何时使用：测试React、Angular、Vue或Next.js应用

活动	参考文件
测试React应用	react.md
测试Angular应用	angular.md
测试Vue/Nuxt应用	vue.md
测试Next.js应用	nextjs.md

重构与维护

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

活动	参考文件
重构为页面对象模型	page-object-model.md, test-suite-structure.md
改进测试组织	test-suite-structure.md, page-object-model.md
提取公共设置/拆卸	fixtures-hooks.md
替换脆弱的选择器	locators.md
移除显式等待	assertions-waiting.md
创建测试数据工厂	test-data.md
配置设置	configuration.md

基础设施与配置

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

活动	参考文件
配置Playwright项目	configuration.md, projects-dependencies.md
设置CI/CD流水线	ci-cd.md, github-actions.md
GitHub Actions设置	github-actions.md
GitLab CI设置	gitlab.md
其他CI提供商	other-providers.md
Docker/容器设置	docker.md
全局设置与拆卸	global-setup.md
项目依赖	projects-dependencies.md
优化测试性能	performance.md, test-suite-structure.md
配置并行执行	parallel-sharding.md, performance.md
隔离工作线程之间的测试数据	fixtures-hooks.md, performance.md
测试覆盖率	test-coverage.md
测试报告/工件	reporting.md

高级模式

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

活动	参考文件
模拟API响应	test-suite-structure.md, network-advanced.md
网络拦截	network-advanced.md, assertions-waiting.md
GraphQL模拟	network-advanced.md
HAR录制/回放	network-advanced.md
自定义夹具	fixtures-hooks.md
高级等待策略	assertions-waiting.md
OAuth/SSO模拟	third-party.md, multi-context.md
支付网关模拟	third-party.md
邮件/短信验证模拟	third-party.md
控制台错误时失败	console-errors.md
安全测试（XSS、CSRF）	security-testing.md
性能预算与Web Vitals	performance-testing.md
Lighthouse集成	performance-testing.md
测试注解（skip、fixme）	annotations.md
测试标签（@smoke、@fast）	test-tags.md
用于报告的测试步骤	annotations.md

快速决策树

您正在做什么？
│
├─ 编写新测试？
│  ├─ 端到端测试 → core/test-suite-structure.md, core/locators.md, core/assertions-waiting.md
│  ├─ 组件测试 → testing-patterns/component-testing.md
│  ├─ API测试 → testing-patterns/api-testing.md, core/test-suite-structure.md
│  ├─ GraphQL测试 → testing-patterns/graphql-testing.md
│  ├─ 视觉回归测试 → testing-patterns/visual-regression.md
│  ├─ 视觉/Canvas测试 → testing-patterns/canvas-webgl.md, core/test-suite-structure.md
│  ├─ 可访问性测试 → testing-patterns/accessibility.md
│  ├─ 移动端/响应式测试 → advanced/mobile-testing.md
│  ├─ 国际化/本地化测试 → testing-patterns/i18n.md
│  ├─ Electron应用测试 → testing-patterns/electron.md
│  ├─ 浏览器扩展测试 → testing-patterns/browser-extensions.md
│  ├─ 多用户测试 → advanced/multi-user.md
│  ├─ 表单验证测试 → testing-patterns/forms-validation.md
│  └─ 拖放测试 → testing-patterns/drag-drop.md
│
├─ 测试特定功能？
│  ├─ 文件上传/下载 → testing-patterns/file-operations.md, testing-patterns/file-upload-download.md
│  ├─ 日期/时间依赖 → advanced/clock-mocking.md
│  ├─ WebSocket/实时 → browser-apis/websockets.md
│  ├─ 地理位置/权限 → browser-apis/browser-apis.md
│  ├─ OAuth/SSO模拟 → advanced/third-party.md, advanced/multi-context.md
│  ├─ 支付/邮件/短信 → advanced/third-party.md
│  ├─ iframe → browser-apis/iframes.md
│  ├─ Canvas/WebGL/图表 → testing-patterns/canvas-webgl.md
│  ├─ Service Worker/PWA → browser-apis/service-workers.md
│  ├─ 国际化/本地化 → testing-patterns/i18n.md
│  ├─ 安全（XSS、CSRF） → testing-patterns/security-testing.md
│  └─ 性能/Web Vitals → testing-patterns/performance-testing.md
│
├─ 架构决策？
│  ├─ POM与夹具 → architecture/pom-vs-fixtures.md
│  ├─ 测试类型选择 → architecture/test-architecture.md
│  ├─ 模拟与实际服务 → architecture/when-to-mock.md
│  └─ 测试套件结构 → core/test-suite-structure.md
│
├─ 框架特定测试？
│  ├─ React应用 → frameworks/react.md
│  ├─ Angular应用 → frameworks/angular.md
│  ├─ Vue/Nuxt应用 → frameworks/vue.md
│  └─ Next.js应用 → frameworks/nextjs.md
│
├─ 身份验证测试？
│  ├─ 基本认证模式 → advanced/authentication.md
│  └─ 复杂流程（MFA、重置） → advanced/authentication-flows.md
│
├─ 测试失败/不稳定？
│  ├─ 不稳定测试调查 → debugging/flaky-tests.md
│  ├─ 元素未找到 → core/locators.md, debugging/debugging.md
│  ├─ 超时问题 → core/assertions-waiting.md, debugging/debugging.md
│  ├─ 竞态条件 → debugging/flaky-tests.md, debugging/debugging.md
│  ├─ 仅多工作线程时不稳定 → debugging/flaky-tests.md, infrastructure-ci-cd/performance.md
│  ├─ 状态泄漏/隔离 → debugging/flaky-tests.md, core/fixtures-hooks.md
│  ├─ 控制台/JS错误 → debugging/console-errors.md, debugging/debugging.md
│  └─ 一般调试 → debugging/debugging.md
│
├─ 测试错误场景？
│  ├─ 网络故障 → debugging/error-testing.md, advanced/network-advanced.md
│  ├─ 离线（意外） → debugging/error-testing.md
│  ├─ 离线优先/PWA → browser-apis/service-workers.md
│  ├─ 错误边界 → debugging/error-testing.md
│  └─ 表单验证 → testing-patterns/forms-validation.md, debugging/error-testing.md
│
├─ 重构现有代码？
│  ├─ 实现POM → core/page-object-model.md
│  ├─ 改进选择器 → core/locators.md
│  ├─ 提取夹具 → core/fixtures-hooks.md
│  ├─ 创建数据工厂 → core/test-data.md
│  └─ 配置设置 → core/configuration.md
│
├─ 设置基础设施？
│  ├─ CI/CD → infrastructure-ci-cd/ci-cd.md
│  ├─ GitHub Actions → infrastructure-ci-cd/github-actions.md
│  ├─ GitLab CI → infrastructure-ci-cd/gitlab.md
│  ├─ 其他CI提供商 → infrastructure-ci-cd/other-providers.md
│  ├─ Docker/容器 → infrastructure-ci-cd/docker.md
│  ├─ 分片/并行 → infrastructure-ci-cd/parallel-sharding.md
│  ├─ 报告/工件 → infrastructure-ci-cd/reporting.md
│  ├─ 全局设置/拆卸 → core/global-setup.md
│  ├─ 项目依赖 → core/projects-dependencies.md
│  ├─ 测试性能 → infrastructure-ci-cd/performance.md
│  ├─ 测试覆盖率 → infrastructure-ci-cd/test-coverage.md
│  └─ 项目配置 → core/configuration.md, core/projects-dependencies.md
│
├─ 组织测试？
│  ├─ 跳过/修复/慢速测试 → core/annotations.md
│  ├─ 测试标签（@smoke、@fast） → core/test-tags.md
│  ├─ 过滤测试（--grep） → core/test-tags.md
│  ├─ 测试步骤 → core/annotations.md
│  └─ 条件执行 → core/annotations.md
│
└─ 运行测试子集？
   ├─ 按标签（@smoke、@critical） → core/test-tags.md
   ├─ 排除慢速/不稳定测试 → core/test-tags.md
   ├─ PR与夜间测试 → core/test-tags.md, infrastructure-ci-cd/ci-cd.md
   └─ 项目特定过滤 → core/test-tags.md, core/configuration.md

测试验证循环

编写或修改测试后：

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