playwright

Playwright 浏览器自动化

使用此技能通过 Playwright 操作真实浏览器：编写端到端测试，让选择器和测试保持稳健，拦截并模拟网络流量，在并行工作进程和 CI 中运行测试套件，以无头模式抓取和提取数据，并通过快照扫描检查无障碍性。这是一个针对单一指定工具的工具技能。测试策略和框架选择请参阅 qa-methodology；前端组件和架构设计请参阅 frontend-engineering。此技能负责操作 Playwright 工具本身。

操作约定

1. 运行前先阅读测试套件。 运行任何内容之前，检查 playwright.config.*、项目、baseURL、webServer、工作进程、重试次数和报告器。切勿假定 README 中的测试命令就是正确命令。
2. 根据行为定位，而非根据布局定位。 优先使用面向用户的定位器（getByRole、getByLabel、getByText），而不是会将标记结构写死的 CSS/XPath。与用户可见行为关联的测试经得起重构；与结构关联的测试则会因重构而失效。
3. 在边界处模拟。 在 page.route() 中模拟外部 HTTP，而不要修补页面内代码。模拟被测依赖的边界，而不是被测代码本身；模拟声称要验证的内容，测试就毫无证明力。
4. 有计划地并行运行。 Playwright 会为每项测试提供隔离的浏览器上下文。根据机器和测试套件调整 workers 和分片，绝不让测试通过全局变量共享可变状态。
5. 在边界处验证。 测试通过的可靠性取决于断言。断言用户可见的结果（可见文本、URL、启用／禁用状态），而非实现细节。
6. 控制证据范围。 仅在失败时捕获跟踪记录、屏幕截图和视频；概述 JSON 报告，而不要直接倾倒报告内容；绝不要在聊天中粘贴完整 HTML 转储或会话 Cookie。

pwrun 脚本

scripts/pwrun 是围绕 Playwright 测试套件构建的 Agent 优先型冒烟测试工具。即使未安装 node 或 Playwright，doctor、inventory 和 report 也能运行，因此 Agent 可在任何环境中检查测试套件并排查 CI 报告。

scripts/pwrun doctor --json                     # node, @playwright/test, browsers, config availability
scripts/pwrun inventory --json                  # config, projects, spec files in the suite
scripts/pwrun report --report test-results.json --json   # summarize a Playwright JSON report
scripts/pwrun smoke --url http://localhost:3000 --json   # delegate a smoke run to npx playwright test

退出代码：0 表示成功，1 表示分析错误，2 表示用法错误，127 表示缺少依赖项（node/playwright），124 表示委托超时。每个命令都支持 --json；即使未安装任何工具链，--help 也能运行。

对于 smoke，--config 会传递给 Playwright。目标 URL 的优先级依次为 --url、继承的 PW_SMOKE_URL、继承的 BASE_URL，最后是 http://localhost:3000；所选目标会作为 PW_SMOKE_URL 传递给提供的脚手架。JSON 结果会分别列出 requested_url 和 navigation_evidence。捆绑的示例规范会记录 page.goto() 之后到达的 URL；自定义规范需要使用 pwrun-navigation 注解，才能提供相同的运行时证据。requested_target_origin_observed 用于说明是否有任何已记录的导航到达了请求的来源。

E2E 测试编写

• 使用 test.describe 代码块、test.beforeEach 设置以及按功能划分的 fixture 文件来组织测试套件。保持测试规范简短，聚焦于单个用户旅程，并以易读的叙述方式编写。
• 使用 Playwright 的 Web 优先断言（expect(locator).toBeVisible()、.toHaveText()、.toHaveURL()）——它们会自动重试直至超时，是稳定 E2E 测试的基石。避免使用 page.waitForTimeout 手动休眠。
• 在配置中使用 webServer 启动被测应用（Playwright 会启动应用、等待就绪并在结束时将其关闭），或在冒烟测试中通过 baseURL 重用已运行的实例。
• 编写模式、fixture 和页面对象模型：references/01-e2e-authoring.md。

选择器的健壮性

• 优先使用角色、标签、文本和占位符定位器——它们描述页面的方式与用户一致。仅在与布局相关的场景下使用 CSS（例如，使用 getByTestId 定位仅供测试使用的 ID）。
• 链式组合并筛选定位器（getByRole('row').filter({ hasText: 'Acme' })），不要构造冗长脆弱的选择器。重新查询，而不是保存已失效的元素句柄。
• 修复不稳定的测试时，应找出具体是哪个选择器匹配了多个或零个元素，而不是添加休眠或使用 first()。可能匹配到错误目标的选择器迟早会出问题。
• 选择器优先级规则和不稳定选择器修复流程：references/02-selectors.md。

网络拦截与模拟

• 使用 page.route() 拦截请求，并对其执行 fulfill、abort 或 continue。可用此方法模拟第三方 API、注入测试数据、模拟离线或慢速网络，以及拦截会干扰测试的分析和追踪请求。
• 在路由层模拟请求，并使用符合实际情况的响应正文和内容类型。切勿拦截测试本身要验证的服务器，也不要对测试依赖的 page.goto 导航进行路由拦截。
• 使用 page.on('request')/page.on('response') 捕获请求，以断言应用实际发送的内容。模式和注意事项：references/03-network-interception-and-mocking.md。

并行工作进程

• workers 用于设置并行运行测试规格的进程数；fullyParallel 则允许每个测试规格文件都在多个工作进程中运行。根据 CPU 核心数和浏览器内存进行扩容，而不是一味追求“越多越好”。
• 对大型测试套件，可将测试分片到多个 CI 作业（--shard=1/4）。每项测试都在独立的浏览器上下文中运行，因此默认已实现隔离——请保持这一点：不要共享全局变量或存储状态，也不要让测试依赖执行顺序。
• 工作进程数量、分片计算和隔离陷阱：references/04-parallel-workers-and-sharding.md。

CI 集成

• 在运行器上安装浏览器和操作系统依赖（npx [email protected] install --with-deps），固定 Playwright 版本，并缓存 ~/.cache/ms-playwright。
• 配置 webServer、retries（仅在 CI 上重试不稳定的测试）和 trace: 'on-first-retry'，以便排查失败原因。使用 html/json/github 报告结果，并在失败时上传构建产物。
• 使用 scripts/pwrun report --json 根据 JSON 报告排查 CI 故障——它会汇总统计数据、失败的测试规格和错误消息，无需打开浏览器。完整的 CI 配方：references/05-ci-integration.md。

抓取与无头浏览

• 直接调用浏览器 API（chromium.launch({ headless: true })、newContext、page.goto）加载由 JavaScript 渲染的页面，然后使用定位器和 innerText/属性访问提取内容，并整理为结构化记录——提取、验证、保存。
• 遵守 robots.txt、服务条款和速率限制；限制抓取的页面数量并设置延迟。要绕过 Cloudflare/DDoS-GUARD 挑战，请转向 flaresolverr——此技能无法解决挑战。
• 抓取流程、分页和礼貌的数据提取：references/06-scraping-and-headless.md。

无障碍快照检查

• 使用 @axe-core/playwright 执行完整扫描，在 CI 中或按需发现 WCAG 违规（对比度、地标、ARIA 误用）。
• 使用 Playwright 的 ARIA 快照（expect(page).toMatchAriaSnapshot()）进行稳定且关注无障碍的断言：它会比较无障碍树，因此能发现结构和标签回归，且读起来就像规格断言。谨慎更新，切勿不加思考地使用 --update-snapshots。
• 扫描设置、快照管理规范和违规修复：references/07-accessibility-and-debugging.md。

有头调试

• 使用有头模式运行（--headed），通过 --slow-mo 减慢操作速度，或使用 --debug / PWDEBUG=1 和 page.pause() 断点进入检查器。
• 使用 npx [email protected] codegen <url> 生成入门测试，然后将生成的选择器强化为面向用户的定位器。
• 测试失败时：读取跟踪记录（--trace on），其中记录了失败操作的网络、DOM 快照和控制台信息。先使用 scripts/pwrun report --report <json> --json 查看失败摘要。
• 调试工作流见 references/07-accessibility-and-debugging.md。

参考文档索引

何时加载	参考文档
编写或组织规格、夹具、页面对象	references/01-e2e-authoring.md
选择器不稳定或匹配了错误元素	references/02-selectors.md
模拟或拦截 API/网络流量	references/03-network-interception-and-mocking.md
加快大型测试套件运行或进行分片	references/04-parallel-workers-and-sharding.md
将 Playwright 接入 CI 或排查 CI 故障	references/05-ci-integration.md
提取数据或以无头模式浏览	references/06-scraping-and-headless.md
无障碍扫描、aria 快照或调试失败的测试	references/07-accessibility-and-debugging.md
来源、版本观察结果和刷新流程	references/00-source-index.md

随附内容

• scripts/pwrun：冒烟测试工具 — doctor、inventory、report、smoke，均支持 --json。
• tests/test_pwrun.py + tests/fixtures/sample-report.json：用于该工具的确定性测试（无需 node/浏览器）。
• tests/test_pwrun_scaffold.py：范围有限的本地服务器/浏览器集成检查；安装了 @playwright/test 和 Chromium 时运行。
• templates/playwright.config.ts、templates/example.spec.ts、templates/accessibility.spec.ts：可复制到测试套件中的脚手架。
• references/：八份带日期、按来源编入索引的参考文档，涵盖上述操作主题。

验证范围

声明	最低证据
工具链已就绪	scripts/pwrun doctor --json 报告 node、@playwright/test 和浏览器均可用
已了解测试套件	scripts/pwrun inventory --json 列出配置文件和规格文件
测试通过	对目标规格运行 npx [email protected] test 并以代码 0 退出（或委托给 smoke）
CI 故障已说明	scripts/pwrun report --report test-results.json --json 列出失败的规格和错误
已覆盖无障碍	axe 扫描在声明的严重级别下零违规，且 aria 快照匹配
覆盖的流程没有回归	测试套件在配置的工作线程/分片设置下运行，并记录预期/不稳定/意外的计数

严格限制

• 绝不通过模拟被测代码来强行让测试通过 — 只能模拟其边界。
• 绝不违反 robots.txt、服务条款或速率限制进行抓取；绝不收集凭据或个人数据，也绝不将身份验证/会话存储提取到已提交的文件中。
• 绝不提交 playwright/.auth/* 存储状态、.env 或浏览器凭据。
• 绝不盲目运行 --update-snapshots 来“修复” aria 快照差异 — 先检查具体变更。
• 绝不将原始 HTML、完整跟踪文件或受保护内容的截图贴到聊天中；改用 pwrun report 概述。
• CI 中的有头浏览器需要显示服务器（例如 xvfb）— 绝不假定运行器上存在显示器。

不适用场景

• 测试策略、框架选择或 QA 流程 — 请转至 qa-methodology。
• 前端组件、状态或架构设计，或实现指导 — 请转至 frontend-engineering；React 专属的组件和 hooks 工作请转至 react。
• 绕过 Cloudflare/DDoS-GUARD 挑战 — 请转至 flaresolverr。
• 大规模负载/性能测试（k6、Locust、Gatling、JMeter）— 相关方法论位于 qa-methodology 的性能测试参考文档中。
• 通过原始 HTTP 获取静态内容 — 请使用普通 HTTP 客户端；Playwright 适用于由 JavaScript 渲染的页面和浏览器工作流。

主题覆盖关键词

目录的自动主题扫描会在此文件中搜索覆盖关键词。下方明确写出了两组别名，以便扫描同时匹配两种写法：e2e|end-to-end 覆盖浏览器级测试（E2E、end-to-end 和 e2e 指的是同一种工作流），debug|head 覆盖此技能中的有头调试工作流。其他所有主题（选择器稳健性、网络拦截、并行工作器、CI 集成、抓取、无障碍快照、模拟）均在上文的章节中按名称列出。