qa-testing-playwright

QA 测试（Playwright）

核心文档：

• https://playwright.dev/docs/best-practices
• https://playwright.dev/docs/locators
• https://playwright.dev/docs/auth
• https://playwright.dev/docs/api-testing
• https://playwright.dev/docs/test-retries
• https://playwright.dev/docs/test-snapshots
• https://playwright.dev/docs/trace-viewer
• https://playwright.dev/docs/test-sharding
• https://playwright.dev/docs/ci
• https://playwright.dev/docs/pom
• https://playwright.dev/docs/test-agents
• https://playwright.dev/docs/clock
• https://playwright.dev/docs/getting-started-cli
• https://playwright.dev/docs/test-components
• https://playwright.dev/docs/test-parallel#test-locks
• https://playwright.dev/docs/release-notes（固定版本前请检查当前版本）

快速参考

需求	前往
运行 Playwright 工作流	## Workflow
应用默认设置和编写规则	## Defaults 和 ## Authoring Rules
调试不稳定或受阻的运行	## Debugging Checklist 和 ## Execution Preflight
判断工具是否适用、选择器、不稳定测试的排查顺序及分片成本	## Expert Judgment
加载模板和参考资料	## Resources 和 ## Templates

默认原则

• 保持 E2E 精简：只保护关键用户旅程；将覆盖率下沉到单元测试、集成测试和契约测试。
• 定位器优先级：getByRole → getByLabel/getByText → getByTestId（备用）。
• 等待：依赖 Playwright 自动等待和面向 Web 的断言；不要使用 sleep 或基于时间的等待。
• 隔离：测试必须能够单独、并行且按任意顺序运行；消除共享可变状态。当共享资源无法隔离（外部服务、全局账户设置）时，声明具名测试锁（1.63+：test(title, { lock: 'user-settings' }, fn)），而不是为整个文件设置 workers: 1 或使用 describe.serial。
• 本地执行方式：先选择一种服务器拓扑（共享开发栈或由 Playwright 管理的 webServer），然后使用精确的测试文件或具名批次，并加上 --workers=1 进行排查。
• Flaky 测试处理方式：重试是调试工具；重跑通过应视为失败信号，并修复根本原因。
• CI 中的 Flaky 测试：优先使用内置的 failOnFlakyTests（1.52+）；自定义 reporter 模板已过时，仅适用于锁定在 1.52 之前版本的项目。
• CI 执行方式：在 PR 上设置冒烟测试门禁；按计划分片并行运行回归测试；始终保留产物（trace/video/screenshot）。
• 判定依据：断言用户可见的结果；如果能直接验证可见结果，就不要等待无关的网络请求。
• AI 使用方式：使用 Playwright codegen、测试 Agent 和 MCP 进行脚手架搭建与探索，然后手动完善断言和 fixtures。
• 组件测试：使用 @playwright/test（1.62+）内置的 stories/gallery mount('components/X/Story') fixture。@playwright/experimental-ct-* 包已于 1.63 冻结，文档现已说明这些包已移除；迁移前请停留在 1.62。参见 references/playwright-patterns.md#component-testing。
• 视觉回归：如果在 Docker 中使用一套操作系统/浏览器基线就足够，请使用原生的 toHaveScreenshot；如果设计师需要审查差异，或浏览器/操作系统矩阵导致提交基线难以管理，请使用托管服务。参见 references/visual-regression-testing.md。
• 浏览器 MCP：使用 Playwright MCP 生成测试并检查可访问性；使用 Chrome DevTools MCP 调试性能、网络和控制台。参见 references/playwright-mcp.md。
• CLI 使用方式：对于高吞吐量的编码 Agent，优先使用 Playwright CLI（npx playwright cli；shell 命令），而不是 Playwright MCP——这样可以避免 MCP 协议每次调用产生的 token 开销。依赖 CLI 前，请通过 npx playwright cli --version 或发行说明确认已安装版本是否支持，因为 CLI 的可用性和标志会随发行版本而变化。官方文档称其可节省 token，但未给出具体数字；任何具体的 token 数量（例如“每项任务的 token 数”比较）都应根据自己的测量结果进行验证，不要当作可引用的事实。需要持久的浏览器状态和丰富的内省能力时，请使用 MCP（npx playwright mcp）。
• 本地迭代方式：编写测试时，使用 npx playwright test --only-changed=main 仅运行受未提交更改或分支更改影响的测试；这是基于导入图的启发式方法，因此合并前始终要运行完整测试套件（或部署门禁重放）——绝不要将 --only-changed 通过视为已达到发布就绪状态。

快速开始

命令	用途
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 codegen	录制流程并创建测试脚手架
npx playwright init-agents --loop=claude	为 Claude Code 初始化测试 Agent（也支持 --loop=codex、vscode、opencode）
npx playwright test --debug=cli	允许编码 Agent 通过 playwright-cli 附加并调试测试（1.59+）
npx playwright test --last-failed	仅重新运行上次运行中失败的测试
npx playwright test --fail-on-flaky-tests	如果有任何测试不稳定，则使 CI 失败
npx playwright show-trace trace.zip	检查跟踪产物
npx playwright show-report	检查 HTML 报告
npx playwright trace open <trace.zip>	打开跟踪以进行命令行分析；然后运行 trace actions、trace action <n>、trace snapshot <n> --name after、trace close（1.59+）
npx playwright test --only-changed=main	仅运行受 main 之后更改影响的测试（启发式方法——发布前务必再完整运行一次）

本地执行拓扑

默认按以下顺序执行：

1. 如果代码库已提供本地开发栈，先启动一个共享的本地开发栈；优先使用 --no-server 复用它，而不是每次重跑都启动一个全新的应用。
2. 确认处理请求的是哪个构建版本：记录源代码修订版或构建 ID、基础 URL、服务进程/启动命令、环境，以及 Service Worker 或 CDN 缓存状态。端口正在监听并不代表提供的是最新代码；如果无法确认构建身份，请标注为 runtime observed, build identity unverified。
3. 使用一个精确的规范文件或一个命名批次，并设置 --workers=1 进行复现。
4. 修复问题并重跑受影响范围最小的部分。
5. 只有在目标范围测试通过后，才运行部署门禁回放。

默认测试套件层级：

• 冒烟测试：PR 门禁，提供最快反馈。
• 定向批次/规范文件：用于本地问题排查和消除不稳定性。
• 部署门禁回放：回放依赖链或关键用户旅程，以增强发布信心。

除非任务明确要求“立即证明已具备部署就绪条件”，否则不要一开始就在本地重跑完整测试套件。

适用场景

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

不适用场景

场景	改用
单元测试	Jest、Vitest、pytest
API 契约	qa-api-testing-contracts
负载测试	k6、Locust、Artillery
原生移动应用	Appium
纯业务逻辑或数据转换正确性	单元测试——浏览器会增加延迟和不稳定性，却不会带来额外信心
跨团队 API 契约漂移	消费者驱动的契约测试，而不是用 UI 点击路径作为代理
大规模组件级视觉/交互隔离	如果已在使用 Playwright，可采用 Playwright stories/gallery 组件测试（1.62+，稳定版）；如果团队会在托管 UI 中审查视觉差异，可使用 Storybook + Chromatic/Percy（参见默认设置）
数千种输入组合的模糊测试	在单元测试层进行基于属性的测试；E2E 无法承担相应的运行时间

专家判断

Playwright 不适用的场景

如果更快、更便宜的测试层已经能验证相同风险，那么 Playwright（或任何浏览器端到端测试工具）就不是合适的选择：

• 如果类型系统、单元测试或架构／契约检查能够捕获此类 bug，就把测试下沉到这些层——按每项断言计算，端到端测试是成本最高的测试层（启动浏览器、网络、渲染）。
• 如果所谓的“用户旅程”实际上只是一次没有有意义 UI 分支的内部 API 调用，就直接测试 API（使用 request fixture 或专门的 API 测试技能），跳过浏览器。
• 如果你测试的是自己无法控制的第三方界面（支付服务商托管页面、OAuth 同意页面），不要用端到端测试追踪它；应模拟边界，并改为测试你自己的集成契约——第三方 UI 变更会让这些测试天然不稳定，而非偶然如此。
• 如果组件测试或视觉快照已经以低得多的成本覆盖了相同风险，就不要为了“保险起见”在端到端测试中重复覆盖——没有新增风险的重复覆盖是浪费，而非周全。

选择器策略决策规则

按以下顺序选择定位器，并在第一个能明确解析为唯一元素的定位器处停止：

1. 带有可访问名称的 getByRole——屏幕阅读器和真实用户都会依据它进行识别，因此它能经受标记重构。
2. getByLabel / getByText——当元素没有有意义的角色（纯文本、装饰性容器），但可见文案稳定时使用。
3. getByTestId——仅当元素没有稳定的角色／标签时使用（例如画布、拖动手柄、名称重复的列表项），或者语义定位器会迫使你断言实现细节（原始 CSS 类、生成的 ID）时使用。 切勿一开始就退回原始 CSS 或 XPath——这表明标记本身可能需要进行无障碍修复，而不只是测试变通。

不稳定测试的排查顺序（优先获取最快信号）

在修改任何断言之前，按以下顺序对失败进行分类——每一步的成本都严格低于下一步，因此不要跳过：

1. 选择器存在歧义 — 跟踪记录显示定位器解析到 0 个或 2 个以上元素。修复定位器，而不是等待逻辑。
2. 缺少等待 / 竞争条件 — 跟踪记录显示，元素尚不可操作时操作就已触发。改用优先面向网页的断言；绝不要添加固定时长的休眠。
3. 状态泄漏 — 只有在其他测试运行后（并行工作进程、共享固定装置、未清理的测试数据）才会复现。修改此测试自身代码之前，先解决隔离问题。如果无法隔离共享资源，就在恰好会访问该资源的测试上添加命名的 lock（1.63+），而不是串行运行整个测试套件。
4. 环境问题 — 只在 CI 中失败，本地不会失败；在认定是产品缺陷之前，先检查并发、冷启动、CPU 资源不足和容器资源限制。
5. 有状态应用类别 — 对于身份验证占比较高或由后端驱动的应用，在认定是产品缺陷之前，也要将失败归类为 auth-state、state-sync、optional-network 和 degraded-mode（参见 ### Stateful App Failure Classes）。
6. 产品回归 — 只有在跟踪证据排除了第 1–5 项后，才将失败视为反映了被测应用的问题，并据此提交问题或修复。

重试会掩盖上述所有问题；可以使用 retries 在首次 CI 运行时收集证据（跟踪记录/视频），但要将“重试后通过”视为尚未解决的缺陷，而不是通过（failOnFlakyTests: true）。

不稳定测试的取证工具（请根据锁定的版本确认是否可用）：

• retryStrategy: 'isolated'（1.62+）会在末尾逐个重试所有测试，并使用单个工作进程。在套件内失败但隔离运行时通过的测试，说明可能存在干扰（第 3 步）；隔离运行时仍然失败，则问题可能属于第 1、2 或 6 步。
• trace: 'retain-on-failure-and-retries'（1.59+；从 1.61 起提供 video 模式）会保留失败和通过的尝试，方便并排比较。
• 对单个可疑测试使用 --repeat-each=N 可验证修复；--last-failed 只会重新运行上次失败的测试。
• 隔离处理：为测试添加 @flaky 标签、负责人和退出日期，并使用 --grep-invert @flaky 或 Reporter.preprocess() 跳过列表（1.62+）将其排除在门禁之外。没有负责人的隔离测试等同于已删除的测试。

CI 并行化成本分析（示例演算）

分片是以机器成本换取墙钟时间；决定是否分片的计算很直接。假设测试套件单线程运行需要 T 分钟，每个分片有 M 分钟的固定机器开销（检出、安装、下载浏览器），共 N 个分片：

• 每个分片的墙钟时间 ≈ T/N + M。
• 计费的机器总分钟数 ≈ N × (T/N + M) = T + N×M。

示例：T = 60 分钟，M = 3 分钟，即每个分片/作业有 3 分钟固定开销。

• 1 个分片：墙钟时间 = 63 分钟，计费 = 63 机器分钟。
• 4 个分片：墙钟时间 = 60/4 + 3 = 18 分钟，计费 = 4 × 18 = 72 机器分钟。
• 12 个分片：墙钟时间 = 60/12 + 3 = 8 分钟，计费 = 12 × 8 = 96 机器分钟。

分片总会增加机器分钟数（因为要支付 N 次固定开销）——换来的回报是更快地获得 PR 反馈，而不是降低支出。决策时应考虑：对 PR 门禁的冒烟测试套件进行分片（墙钟时间很重要，且套件较小，因此 N×M 较小）；将完整回归测试不分片或少量分片后按计划运行（此时支出比延迟更重要）。选择分片数量前，请用自己的 T 和 M 重新计算这个比例——不要习惯性地照搬 N=4。

编写规则

定位器策略

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

// 2. Label/text locators
await page.getByLabel('Email').fill('[email protected]');

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

不稳定测试控制

• 避免休眠；使用 Playwright 自动等待
• 将重试用作信号，而不是拐杖
• 在 CI 中优先使用内置的 failOnFlakyTests
• 失败时捕获跟踪记录/屏幕截图/视频
• 优先采用符合用户习惯的交互；避免使用 force: true

工作流

• 编写能够证明用户预期结果（意图 + 判定依据）的最小测试。
• 排查前明确执行拓扑：共享开发环境还是 Playwright webServer，并列出准确的启动/停止命令。
• 先用一个确切的测试规范或命名批次复现，再扩大范围。
• 添加更多步骤前，先稳定定位器和断言。
• 明确状态：按测试/工作进程进行数据初始化，以确定性的方式清理，并验证有状态应用的身份验证/订阅/测试数据重置路径。
• 对不属于面向用户判定依据的第三方边界进行模拟或隔离。
• 在 CI 中：分片/并行执行、收集产物，并对重跑后通过的不稳定测试快速失败。

调试清单

如果测试不稳定：

• 首先打开跟踪记录和错误产物；判断失败原因是选择器不明确、缺少等待、状态泄漏，还是服务器拓扑错误。
• 如果跟踪记录跳转到登录页或意外重定向，先将其归类为 auth-state，再修改断言。
• 如果浏览器日志显示边缘请求返回 429 或 Retry-After，判断该请求是否属于判定依据，还是仅为噪声。
• 用语义定位器替换脆弱的选择器；用 expect(...)、支持身份验证的导航辅助函数或针对性的就绪断言替换固定等待。
• 移除对偶发请求的等待；改为断言可见的路由、操作或内容结果。
• 缩短全局超时时间；只有在产品确实需要时才添加作用域超时——优先使用单次操作超时或 test.step(name, fn, { timeout })，而不是提高 playwright.config.ts 中的 timeout。
• 如果只在 CI 中失败，检查并发、冷启动、CPU 资源不足和环境差异。

执行前检查

运行耗时较长的 E2E 测试前，先执行 references/playwright-preflight-sandbox.md 中的预检查（规范路径、端口/主机绑定、单一服务器拓扑、构建锁、每项测试的超时预算、EPERM/EACCES 升级处理），并使用 assets/template-playwright-preflight-checklist.md 记录答案。将 EADDRINUSE、缺少规范/结果路径以及括号路由段上的 shell 通配符失败视为环境故障，而非产品缺陷。

有状态应用的失败类别

• auth-state：受保护的路由意外重定向到登录页，或丢失存储/会话状态。
• state-sync：后端重置或 webhook 已成功，但 UI 尚未同步完成。
• optional-network：边缘请求失败，但面向用户的判定结果仍可能正确。
• degraded-mode：触发了速率限制或降级 UX，应有意对其进行断言。

资源

资源	用途
references/playwright-mcp.md	MCP 和 AI 测试
references/playwright-patterns.md	高级模式
references/playwright-ci.md	CI 配置
references/playwright-authentication.md	身份验证模式和会话管理
references/visual-regression-testing.md	视觉回归（库的权威文档）：原生与托管、基线、阈值
references/api-testing-playwright.md	用于 UI+API 混合测试的 request fixture（契约/架构相关工作见 qa-api-testing-contracts）
references/playwright-preflight-sandbox.md	沙箱/端口预检查和升级处理决策
data/sources.json	文档链接

模板

模板	用途
assets/template-playwright-e2e-review-checklist.md	E2E 审查清单
assets/template-playwright-fail-on-flaky-reporter.js	旧版：仅适用于 Playwright < 1.52，在重跑通过的测试出现不稳定问题时使 CI 失败；其他情况请使用 failOnFlakyTests
assets/test-fail-on-flaky-reporter.test.js	针对旧版不稳定测试报告器的 node --test 检查
assets/template-playwright-preflight-checklist.md	端口／沙箱／超时预检清单

导航

使用快速参考来选择工作流、调试路径或资源。

相关技能

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

验证关卡

交付前，请检查：

• 如果存在 Playwright 项目，请提供准确的测试运行命令，并在环境可用时执行；否则标记为未验证执行。
• 生成的选择器遵循指定的定位器优先级，除非页面情况使其无法实现。
• 输出避免基于 sleep 的等待，并指出要检查的就绪断言或跟踪／调试产物。
• 所有引用的测试文件、配置文件和命令路径均存在于仓库中，或明确标记为拟议内容。

经验反馈循环

如果以往的决策或陷阱与当前任务有关，请在 learnings.consolidated.md 存在时查阅；仅在需要查看历史记录或将其作为可用替代方案时，才使用 learnings.md。否则跳过两者。

应用后，如果遇到了值得记住的模式、需要避免的错误，或令人意外的领域知识，请通过 agents-skills-feedback-loop/scripts/append_learning.py 向 learnings.md 追加一条带日期的条目。不要修改 SKILL.md 本身。