mcpField
P
playwright-triage

playwright-triage

github.com/microsoft开发15.0k176 次安装今天更新
代码仓库

关于 playwright-triage

用于 `microsoft/playwright-cli` 的无人值守问题分诊技能。它指导问题调查与修复；若代码变更应在 `microsoft/playwright` 中完成，也会指导回归测试和上游修复提案。

主要功能

  1. 01分诊 Playwright CLI 问题
  2. 02定位两个代码仓库中的实现
  3. 03使用已发布版本复现问题
  4. 04指导编写回归测试与修复
  5. 05准备上游修复提案

适用场景

  1. 01调查报告的 CLI 缺陷
  2. 02在已发布的软件包版本中复现行为
  3. 03判断修复是否应提交到上游
  4. 04准备回归测试和修复提案

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/microsoft/playwright-cli --skill playwright-triage

安装后在 Claude Code 中输入/playwright-triage确认已加载。

详细介绍

Playwright CLI 问题分类

你会在 microsoft/playwright-cli 的 Issue triage 工作流中无人值守地运行。请先完整阅读共享指南 $AGENT_GUIDES_DIR/triage.md（它是 microsoft/playwright/.github/actions/run-agent/guides/triage.md 的副本），然后完整阅读 CLAUDE.md。该指南介绍如何在任何 Playwright 仓库中对问题进行分类。CLAUDE.md 介绍如何构建、测试和检查本仓库的代码。本文件补充两者都未涵盖的内容：代码的位置、检出目录、如何运行已发布的版本，以及本仓库需要额外完成的事项——在 microsoft/playwright 中修复问题。

代码的位置

本仓库是 npm 包 @playwright/cli：包括 playwright-cli.js 及其更新检查、skillCheck.js、README、skills/playwright-cli/ 中的技能，以及一些针对打包后 CLI 的测试。package.json 固定了该包运行所用的 playwright 和 playwright-core alpha 版本。CLI 位于 microsoft/playwright 的 packages/playwright-core/src/tools/ 中：cli-client/ 包含命令及其选项，cli-daemon/ 包含用于在命令之间保持浏览器开启的守护程序，backend/ 包含命令所运行的工具。大多数 bug 和功能请求都在该处修复。

仅当问题根因位于本仓库管理的文件中时，才在此处修复 bug。skills/playwright-cli/ 是 packages/playwright-core/src/tools/skills/playwright-cli/ 的副本，每次更新时都会由 scripts/update.js 刷新，因此其中的修复也需要同步到上游。

检出目录

$REPO_DIR 是指南中介绍的 microsoft/playwright-cli 检出目录。已在其中运行 npm ci，并安装固定版本所需的浏览器。CLI 默认使用运行器映像中的 Google Chrome。如果未安装，请使用 npx playwright install chrome 安装。该克隆为浅克隆：需要查看历史记录前，先在其中运行 git fetch --unshallow --tags origin。

$PLAYWRIGHT_DIR 是 microsoft/playwright 的克隆，位于 $REPO_DIR 旁边，并检出到 main 的最新提交。已在其中运行 npm ci 和 npm run build，并安装 Chromium、Firefox 和 WebKit。它是本仓库的最新代码：请在那里复现问题，将其写成 tests/mcp/cli-*.spec.ts 中的测试，并使用 tests/mcp/cli-fixtures.ts 中的 cli fixture。npm run test-playwright-cli 会运行这些测试。编写测试前，请完整阅读其中的 AGENTS.md。该文件介绍如何构建、测试和检查代码。该克隆包含完整历史记录，但文件内容会在 Git 需要时才获取，因此可以在那里运行 git log 和 git tag --contains。

固定的版本早于最新代码。npm view playwright-core@<alpha> gitHead 会打印构建该 alpha 版本所用的上游提交。

在 microsoft/playwright 中修复

如果修复位于 $PLAYWRIGHT_DIR，请遵循该目录中指南的 Fix 部分，而不是 $REPO_DIR 中的对应部分：在 $PLAYWRIGHT_DIR 中从 main 创建分支 fix-<n>，将回归测试放入其 tests/mcp/cli-*.spec.ts，按照其 AGENTS.md 的说明进行构建和 lint，并按其约定提交，例如 fix(cli): ...。然后将提案放在 $OUTPUT_DIR/upstream-fix/，而不是 $OUTPUT_DIR/fix/，文件保持相同：

  • fix.patch：在 $PLAYWRIGHT_DIR 中运行 git diff --binary main HEAD 的输出。
  • pr-body.md：按照指南的说明填写。Fixes 行要包含问题的完整 URL：Fixes https://github.com/microsoft/playwright-cli/issues/<n>，这样 PR 就会关闭此仓库中的问题。
  • proposal.json：按照指南的说明填写。最后写入此文件。

发布任务会在 microsoft/playwright 中创建草稿 PR。该仓库的修订工作流会处理评审意见。只保留一个提案：fix/ 或 upstream-fix/，不能同时保留。不要在此处修改 package.json 来引入此修复。它会随下一次 roll 进入 @playwright/cli。

检查两个仓库中关联的 PR。 microsoft/playwright 中的 PR 会通过完整 URL 或 microsoft/playwright-cli#<n> 关联此问题。也要在那里搜索： repo:microsoft/playwright is:pr "playwright-cli/issues/<n>" 和 repo:microsoft/playwright is:pr "playwright-cli#<n>"。来自团队或 microsoft-playwright-automation 的 PR 属于团队 PR。请在 $PLAYWRIGHT_DIR 中验证该仓库里的 PR。

已修复表示主分支最新代码测试通过，而固定版本测试失败。修复会随下一次 roll 到达用户。使用以下命令查找上游 PR，并在备注中注明： git -C $PLAYWRIGHT_DIR log <gitHead of the pinned alpha>..main -- packages/playwright-core/src/tools

已发布的版本

要运行已发布的版本（例如 reporter 的版本或用于二分查找），请创建 $SCRATCH_DIR/playwright-cli-<n>/<version>/，然后在该目录中运行：

npm init -y
npm i @playwright/cli@<version>
npx playwright-cli --help

该目录中没有此仓库的 fixtures。请在该目录中使用 npx playwright-cli 命令运行精简复现，或运行一个会启动这些命令的脚本。通过 data: URL 或脚本中的 http.createServer() 提供页面。完成后运行 npx playwright-cli close-all，以免守护进程继续运行。

npm view @playwright/cli@<version> dependencies.playwright-core 会打印某个版本的 alpha。使用以下命令将回归问题与上游提交对应起来： git -C $PLAYWRIGHT_DIR log <good gitHead>..<bad gitHead> -- packages/playwright-core/src/tools

来自第三方的 PR

不要运行会修改 package.json、package-lock.json、scripts/、 .github/、.azure-pipelines/ 或 .claude/ 的本仓库 PR。对于 microsoft/playwright 中的 PR，适用 $PLAYWRIGHT_DIR/.claude/skills/playwright-triage/SKILL.md 中的列表。

评论

支持 Markdown