qa-testing-playwright

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QA Testing (Playwright)

QA测试（Playwright）

High-signal, cost-aware E2E testing for web applications.

Core docs:

针对Web应用的高价值、成本可控的E2E测试方案。

核心文档：

Defaults (2026)

默认规范（2026版）

Keep E2E thin: protect critical user journeys only; push coverage down (unit/integration/contract).
Locator priority:
```
getByRole
```
→
```
getByLabel
```
/
```
getByText
```
→
```
getByTestId
```
(fallback).
Waiting: rely on Playwright auto-wait + web-first assertions; no sleeps/time-based waits.
Isolation: tests must run alone, in parallel, and in any order; eliminate shared mutable state.
Flake posture: retries are a debugging tool; treat rerun-pass as a failure signal and fix root cause.
CI posture: smoke gate on PRs; shard/parallelize regression on schedule; always keep artifacts (trace/video/screenshot).

精简E2E测试：仅覆盖核心用户流程；将更多测试覆盖下放到单元/集成/契约测试层面。
选择器优先级：
```
getByRole
```
→
```
getByLabel
```
/
```
getByText
```
→
```
getByTestId
```
（备选方案）。
等待机制：依赖Playwright自动等待 + 面向Web的断言；不使用休眠/基于时间的等待。
隔离性：测试必须可独立运行、并行执行且顺序无关；消除共享可变状态。
不稳定测试处理：重试仅作为调试工具；将“重试通过”视为失败信号并修复根本原因。
CI策略：PR阶段运行冒烟测试；定时执行分片/并行化的回归测试；始终保留测试产物（trace/视频/截图）。

Quick Start

快速开始

Command	Purpose
`npm init playwright@latest`	Initialize Playwright
`npx playwright test`	Run all tests
`npx playwright test --grep @smoke`	Run smoke tests
`npx playwright test --project=chromium`	Run a single project
`npx playwright test --ui`	Debug with UI mode
`npx playwright test --debug`	Step through a test
`npx playwright show-trace trace.zip`	Inspect trace artifacts
`npx playwright show-report`	Inspect HTML report

命令	用途
`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`	查看Trace产物
`npx playwright show-report`	查看HTML测试报告

When to Use

适用场景

E2E tests for web applications
Test user authentication flows
Verify form submissions
Test responsive designs
Automate browser interactions
Set up Playwright in CI/CD

Web应用的E2E测试
用户认证流程测试
表单提交验证
响应式设计测试
浏览器交互自动化
在CI/CD中搭建Playwright

When NOT to Use

不适用场景

Scenario	Use Instead
Unit testing	Jest, Vitest, pytest
API contracts	qa-api-testing-contracts
Load testing	k6, Locust, Artillery
Mobile native	Appium

场景	替代方案
单元测试	Jest, Vitest, pytest
API契约测试	qa-api-testing-contracts
性能测试	k6, Locust, Artillery
原生移动端测试	Appium

Authoring Rules

编写规范

Locator Strategy

选择器策略

typescript

// 1. Role locators (preferred)
await page.getByRole('button', { name: 'Sign in' }).click();

// 2. Label/text locators
await page.getByLabel('Email').fill('user@example.com');

// 3. Test IDs (fallback)
await page.getByTestId('user-avatar').click();

typescript

// 1. Role locators (preferred)
await page.getByRole('button', { name: 'Sign in' }).click();

// 2. Label/text locators
await page.getByLabel('Email').fill('user@example.com');

// 3. Test IDs (fallback)
await page.getByTestId('user-avatar').click();

Flake Control

不稳定测试控制

Avoid sleeps; use Playwright auto-wait
Use retries as signal, not a crutch
Capture trace/screenshot/video on failure
Prefer user-like interactions; avoid
```
force: true
```

避免使用休眠；依赖Playwright自动等待
将重试作为问题信号，而非解决方案
失败时捕获trace/截图/视频
优先使用类用户交互；避免使用
```
force: true
```

Workflow

工作流程

Write the smallest test that proves the user outcome (intent + oracle).
Stabilize locators and assertions before adding more steps.
Make state explicit: seed per test/worker, clean up deterministically, mock third-party boundaries.
In CI: shard/parallelize, capture artifacts, and fail fast on rerun-pass flakes.

编写最小化测试用例，验证用户预期结果（意图 + 验证规则）。
在添加更多步骤前，先稳定选择器和断言。
状态显式化：为每个测试/工作进程预置数据，确定性清理，模拟第三方依赖边界。
CI环境中：分片/并行执行，捕获产物，若重试通过则判定为失败并终止流程。

Debugging Checklist

调试检查清单

If something is flaky:

Open trace first; identify whether it is selector ambiguity, missing wait, or state leakage.
Replace brittle selectors with semantic locators; replace sleeps with
```
expect(...)
```
or a targeted wait.
Reduce global timeouts; add scoped timeouts only when the product truly needs it.
If it only fails in CI, look for concurrency, cold-start, CPU starvation, and environment differences.

若测试不稳定：

首先打开trace；确定问题是选择器歧义、缺少等待还是状态泄漏。
用语义化选择器替换脆弱的选择器；用
```
expect(...)
```
或针对性等待替换休眠。
缩短全局超时时间；仅当产品确实需要时才添加局部超时。
若仅在CI中失败，检查并发问题、冷启动、CPU资源不足以及环境差异。

Do / Avoid

建议/禁忌

Make tests independent and deterministic
Use network mocking for third-party deps
Run smoke E2E on PRs; full regression on schedule
"Test everything E2E" as default
Weakening assertions to "fix" flakes
Auto-healing that weakens assertions

确保测试独立且可预测
对第三方依赖使用网络模拟
PR阶段运行冒烟E2E测试；定时执行全量回归测试
将“所有内容都用E2E测试”作为默认方案
弱化断言来“修复”不稳定测试
使用自动修复功能弱化断言

Resources

资源

Resource	Purpose
references/playwright-mcp.md	MCP & AI testing
references/playwright-patterns.md	Advanced patterns
references/playwright-ci.md	CI configurations
data/sources.json	Documentation links

资源	用途
references/playwright-mcp.md	MCP & AI测试
references/playwright-patterns.md	进阶模式
references/playwright-ci.md	CI配置
data/sources.json	文档链接

Templates

模板

Template	Purpose
assets/template-playwright-e2e-review-checklist.md	E2E review checklist
assets/template-playwright-fail-on-flaky-reporter.js	Fail CI on rerun-pass flakes

模板	用途
assets/template-playwright-e2e-review-checklist.md	E2E测试评审清单
assets/template-playwright-fail-on-flaky-reporter.js	不稳定测试重试通过时终止CI

Skill	Purpose
qa-testing-strategy	Overall test strategy
software-frontend	Frontend development
ops-devops-platform	CI/CD integration

技能	用途
qa-testing-strategy	整体测试策略
software-frontend	前端开发
ops-devops-platform	CI/CD集成