playwright

Playwright

何时使用此技能

在用户：

提及 / 关键词

• 提及“Playwright”、“@playwright/test”、“playwright.config.ts”、“trace viewer”或“PWDEBUG”
• 引用导入了 @playwright/test 的 *.spec.ts / *.test.ts 文件

上下文

• 正在尝试为 Web 应用添加或维护 E2E/冒烟测试覆盖
• 正在尝试调试不稳定的 UI 测试（选择器、时序、等待）
• 需要一次性自动化操作（截图、控制台日志、快速流程检查）

目的

• 将 Playwright 工作引导至合适的工作流（测试套件、一次性脚本或调试）
• 规范可防止测试不稳定的模式（定位器、断言、等待）
• 将产物保存在 ./tmp/ 中，以便按预期清理

快速路由

• 编写/维护 @playwright/test 测试套件 → 参阅 references/e2e-with-playwright-test.md
• 认证一次，重复使用状态（storageState） → 参阅 references/auth-and-storage-state.md
• 强化 CI + 配置选项 → 参阅 references/ci-and-config.md
• 定位器、断言、POM、夹具 → 参阅 references/patterns.md
• 夹具（worker 作用域、自动夹具） → 参阅 references/fixtures.md
• 模拟 API / 控制网络 → 参阅 references/api-mocking.md
• 视觉测试（toHaveScreenshot） → 参阅 references/visual-testing.md
• 链接检查 / 检测失效链接 → 参阅 references/link-checking.md
• 不稳定的测试 / trace viewer / 重试 → 参阅 references/debugging.md
• 一次性自动化操作（截图/日志/流程检查） → 参阅 references/ad-hoc-automation.md

不可妥协的要求

• 优先使用 getByRole / getByLabel，而不是 CSS/XPath；仅在需要时添加 data-testid。
• 使用 Web 优先断言（await expect(locator).toBeVisible()），而不是布尔检查。
• 绝不要添加 waitForTimeout() 来“修复”不稳定问题；如果调试时临时使用，在宣布工作“完成”前将其移除。
• 不要默认在所有地方使用 networkidle；应有针对性地使用（SPA / 已知的后台活动可能会造成误导）。
• 对于 CLI Agent 运行，使用精简的报告器以避免日志泛滥；将产物保存在 ./tmp/playwright/ 下。
• 保持测试相互独立；避免跨测试共享状态。

验证

• E2E 测试套件变更：运行 npx playwright test --reporter=line（或 --reporter=dot），并确认故障可以复现。
• 不稳定问题修复：至少运行此前失败的测试 5 次（例如：--repeat-each 5），再宣布问题已修复。
• 对 CI 敏感的变更：在“类 CI”设置下运行测试套件（例如：CI=1 npx playwright test --reporter=line），并确认其行为正常。

来源

• 汇总自上游已安装技能：playwright-best-practices、playwright-testing、playwright-expert、playwright-skill、webapp-testing