名称: qa-testing-playwright 描述: “用于编写端到端网页测试、调试不稳定测试或设置 Playwright CI。涵盖：稳定选择器（getByRole）、并行化/分片、不稳定控制、网络模拟、视觉测试、MCP/AI 自动化和 CI/CD 集成。”
QA 测试（Playwright）
高信号、成本意识的网页应用程序端到端测试。
核心文档:
- https://playwright.dev/docs/best-practices
- https://playwright.dev/docs/locators
- https://playwright.dev/docs/test-retries
- https://playwright.dev/docs/trace-viewer
- https://playwright.dev/docs/test-sharding
- https://playwright.dev/docs/ci
默认设置（2026）
- 保持 E2E 精简：仅保护关键用户旅程；将覆盖率下推（单元/集成/合约）。
- 选择器优先级：
getByRole→getByLabel/getByText→getByTestId（备用）。 - 等待：依赖 Playwright 自动等待 + 网页优先断言；不使用睡眠/基于时间的等待。
- 隔离：测试必须单独运行、并行运行和任意顺序运行；消除共享可变状态。
- 不稳定处理：重试是调试工具；将重新运行通过视为失败信号并修复根本原因。
- CI 处理：PR 上的冒烟门；按计划分片/并行化回归；始终保留工件（跟踪/视频/截图）。
快速开始
| 命令 | 目的 |
|---|---|
npm init playwright@latest |
初始化 Playwright |
npx playwright test |
运行所有测试 |
npx playwright test --grep @smoke |
运行冒烟测试 |
npx playwright test --project=chromium |
运行单个项目 |
npx playwright test --ui |
使用 UI 模式调试 |
npx playwright test --debug |
逐步执行测试 |
npx playwright show-trace trace.zip |
检查跟踪工件 |
npx playwright show-report |
检查 HTML 报告 |
何时使用
- 网页应用程序的端到端测试
- 测试用户认证流程
- 验证表单提交
- 测试响应式设计
- 自动化浏览器交互
- 在 CI/CD 中设置 Playwright
何时不使用
| 场景 | 替代使用 |
|---|---|
| 单元测试 | Jest, Vitest, pytest |
| API 合约 | qa-api-testing-contracts |
| 负载测试 | k6, Locust, Artillery |
| 移动原生 | Appium |
编写规则
选择器策略
// 1. 角色选择器（首选）
await page.getByRole('button', { name: '登录' }).click();
// 2. 标签/文本选择器
await page.getByLabel('电子邮件').fill('user@example.com');
// 3. 测试 ID（备用）
await page.getByTestId('用户头像').click();
不稳定控制
- 避免睡眠；使用 Playwright 自动等待
- 将重试用作信号，而非依赖
- 失败时捕获跟踪/截图/视频
- 优先用户类交互；避免
force: true
工作流
- 编写最小的测试以证明用户结果（意图 + 预言）。
- 在添加更多步骤之前稳定选择器和断言。
- 使状态明确：每个测试/工作线程播种，确定性清理，模拟第三方边界。
- 在 CI 中：分片/并行化，捕获工件，并在重新运行通过的不稳定情况下快速失败。
调试检查清单
如果某些内容不稳定：
- 首先打开跟踪；识别是选择器模糊、缺少等待还是状态泄漏。
- 用语义选择器替换脆弱的選擇器；用
expect(...)或有针对性的等待替换睡眠。 - 减少全局超时；仅在产品真正需要时添加作用域超时。
- 如果仅在 CI 中失败，查找并发、冷启动、CPU 饥饿和环境差异。
做 / 避免
-
使测试独立且确定性
-
对第三方依赖使用网络模拟
-
在 PR 上运行冒烟 E2E；按计划运行完整回归
-
默认情况下“一切 E2E 测试”
-
削弱断言以“修复”不稳定
-
削弱断言的自动修复
资源
| 资源 | 目的 |
|---|---|
| references/playwright-mcp.md | MCP & AI 测试 |
| references/playwright-patterns.md | 高级模式 |
| references/playwright-ci.md | CI 配置 |
| data/sources.json | 文档链接 |
模板
| 模板 | 目的 |
|---|---|
| assets/template-playwright-e2e-review-checklist.md | E2E 审查检查清单 |
| assets/template-playwright-fail-on-flaky-reporter.js | 在重新运行通过的不稳定时使 CI 失败 |
相关技能
| 技能 | 目的 |
|---|---|
| qa-testing-strategy | 总体测试策略 |
| software-frontend | 前端开发 |
| ops-devops-platform | CI/CD 集成 |