playwright

Playwright

当工作涉及 Playwright Test、浏览器自动化、E2E 测试、定位器、fixture、身份验证设置、网络模拟、跟踪记录、CI、与 UI 配套的 API 测试、组件故事或基于 Playwright 构建的 Agent 浏览器工具时，请使用此技能。

快照：@playwright/[email protected] / [email protected] / [email protected]（已核实为截至 2026-10-01 的当前版本）。如果版本不同，请从 source-map.md 更新。

工作流

1. 修改代码前，检查本地 Playwright 环境：
   • 检查 @playwright/test、playwright、可选的 @playwright/browser-*、遗留的 @playwright/experimental-ct-*、Node 和 Docker 镜像标签的版本。
   • 检查配置：playwright.config.ts / .js、testDir、项目、use 选项、webServer、报告器、重试/retryStrategy/工作线程。
   • 检查测试布局：测试规格、设置项目、fixture、POM 类、playwright/.auth、快照、故事/图库和 CI 工作流。
   • 明确运行时用途：E2E UI、仅 API、复用身份验证、网络模拟、视觉/无障碍检查、组件故事或由 Agent 驱动的探索。
2. 如果用户询问最新/当前行为、版本不明确，或工作涉及 CI、CT 或 Agent 工具，请更新文档。从 source-map.md 开始。
3. 关于安装、Library 与 Test 的区别、配置、项目、webServer 和 CLI，请使用 setup-core.md。
4. 关于定位器、操作、自动等待、Web 优先断言和反模式，请使用 locators-assertions.md。
5. 关于 fixture、POM、身份验证/storageState、并行执行、测试锁和网络/HAR 模拟，请使用 fixtures-auth-network.md。
6. 关于跟踪记录、UI Mode、调试、CI/分片/Docker、API 测试、CT、无障碍/视觉检查和 Agent 工具，请使用 debugging-ci-advanced.md。
7. 按照现有项目风格实现：
   • E2E 测试优先使用 @playwright/test。仅在不使用 Test Runner 的独立脚本/自动化场景中使用 playwright 库。
   • 更改 Playwright 软件包版本后，重新安装对应版本的浏览器二进制文件。
   • 遵循本地的定位器惯例、fixture 模式和 CI 构件设置，但这些做法与官方指南冲突时除外。

Playwright 判断

• 优先使用面向用户的定位器：先用 getByRole，然后用 label/placeholder/text/alt/title，最后用 getByTestId。除非有充分理由，否则避免使用 CSS/XPath。
• 优先使用 locator.visible()，而不是 :visible CSS 伪类。如果契约允许，优先使用唯一的角色/名称，而不是可见性筛选器。
• 仅当目标可能位于任意 iframe 中时，才在不带选择器的情况下使用 page.frameLocator()；其余定位器仍必须在单个 frame 内解析。
• 使用 Web 优先断言 await expect(...).toBeVisible()（及同类断言）。绝不要使用 expect(await locator.isVisible()).toBe(true)。
• 信任自动等待。不要提交基于 waitForTimeout / sleep 的同步代码。
• 保持测试隔离。优先使用 setup 项目的 storageState 或 worker 级账号，而不是在每个测试中共享可变的登录状态。
• 对于共享的外部资源，声明一个具名 lock，而不是将整个文件串行化。在默认/串行模式下，某个测试上的锁会在整个文件执行期间持有。
• 在 context/page.route 处模拟第三方或不可控网络；在触发操作之前启动 waitForResponse。
• 本地调试路径：UI Mode → CI 故障时使用 Trace Viewer → 使用 --debug / Inspector 逐步调试。
• CI 默认设置：forbidOnly、重试、trace: 'on-first-retry'、screenshot: 'only-on-failure'；使用 --with-deps 或版本匹配的 Docker 镜像（mcr.microsoft.com/playwright:v1.63.0-noble）安装；通过分片扩展，而不只是增加 worker。
• 组件测试使用内置的 mount，针对由应用自身开发服务器提供的故事库运行。1.63+ 不要添加 @playwright/experimental-ct-*。在这些包完成迁移之前，请使用 1.62。
• 对于在仓库内编写测试的编码 Agent，若 Playwright CLI 可用，优先使用它；对于实时探索式浏览器循环，使用 Playwright MCP。不要将测试框架的浏览器工具与 @playwright/mcp 混淆。

验证

优先使用仓库现有的检查。对于有实际意义的 Playwright 工作，包含以下相关子集：

• 针对变更的规格/项目运行聚焦的 bunx playwright test（使用 --project、文件路径或 -g 标题）。
• 定位器/时序行为不明确时，使用 UI Mode 或 headed 运行。
• 对于不稳定测试、可操作性或网络故障，检查 Trace 或 HTML 报告。
• 更改重试、分片、报告器、Docker 标签、身份验证设置或 webServer 时，运行符合 CI 配置的冒烟测试。
• 仅当视觉基线有意变更时，才更新快照（-u）；尽可能在与 CI 相同的操作系统/浏览器上生成。
• 如果项目会对测试进行类型检查，则对 TypeScript 配置、fixtures 和 POM 辅助程序执行类型检查。