Back to Details

playwright-triage

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Playwright CLI Issue Triage

Playwright CLI Issue 分类诊断

You run unattended in the Issue triage workflow of 
microsoft/playwright-cli
. First read the shared guide, 
$AGENT_GUIDES_DIR/triage.md
, a copy of microsoft/playwright/.github/actions/run-agent/guides/triage.md, and then CLAUDE.md, both in full. The guide says how to triage an issue in any Playwright repo. CLAUDE.md says how to build, test and lint this one. This file covers what neither has: where the code is, the checkouts, how to run a published version, and the outcome that this repo adds, a fix in 
microsoft/playwright
.
你会在 
microsoft/playwright-cli
的 Issue triage 工作流中无人值守地运行。首先完整阅读共享指南 
$AGENT_GUIDES_DIR/triage.md
（它是 microsoft/playwright/.github/actions/run-agent/guides/triage.md 的副本），然后完整阅读 CLAUDE.md。该指南介绍了如何在任何 Playwright 仓库中对 issue 进行分类诊断。CLAUDE.md 介绍了如何构建、测试和 lint 本仓库。本文件则补充前两者未涵盖的内容：代码位置、各 checkout、如何运行已发布版本，以及本仓库额外产生的结果——在 
microsoft/playwright
中进行修复。

Where the code is

代码位置

This repo is the npm package 
@playwright/cli
: 
playwright-cli.js
with its update check, 
skillCheck.js
, the README, the skill in 
skills/playwright-cli/
and some tests of the packaged CLI. 
package.json
pins the alpha of 
playwright
and 
playwright-core
that the package runs. The CLI is in 
microsoft/playwright
, in 
packages/playwright-core/src/tools/
: 
cli-client/
has the commands and their options, 
cli-daemon/
has the daemon that keeps the browser open between commands, and 
backend/
has the tools that the commands run. Most bugs and most feature requests are fixed there.
Fix a bug here only when the cause is in a file that this repo owns. 
skills/playwright-cli/
is a copy of 
packages/playwright-core/src/tools/skills/playwright-cli/
, which 
scripts/update.js
refreshes on a roll, so its fix is upstream too.
本仓库是 npm 包 
@playwright/cli
：包括带有更新检查逻辑的 
playwright-cli.js
、
skillCheck.js
、README、位于 
skills/playwright-cli/
的 skill，以及该打包 CLI 的一些测试。
package.json
锁定了该包运行时使用的 
playwright
和 
playwright-core
alpha 版本。
CLI 位于 
microsoft/playwright
的 
packages/playwright-core/src/tools/
中：
cli-client/
包含命令及其选项，
cli-daemon/
包含在命令之间保持浏览器打开的 daemon，
backend/
包含命令运行所调用的工具。大多数 bug 和大多数功能请求都在那里修复。
只有当问题原因位于本仓库负责的文件中时，才应在这里修复 bug。
skills/playwright-cli/
是 
packages/playwright-core/src/tools/skills/playwright-cli/
的副本，后者会在 roll 时由 
scripts/update.js
刷新，因此对前者的修复同样属于上游修复。

The checkouts

各 checkout

$REPO_DIR
is the checkout of 
microsoft/playwright-cli
that the guide describes. 
npm ci
ran in it, and the browsers of the pinned version are installed. The CLI uses Google Chrome from the runner image by default. When it is missing, install it with 
npx playwright install chrome
. The clone is shallow: run 
git fetch --unshallow --tags origin
in it before you need its history.
$PLAYWRIGHT_DIR
is a clone of 
microsoft/playwright
at the tip of 
main
, next to 
$REPO_DIR
. 
npm ci
and 
npm run build
ran in it, and Chromium, Firefox and WebKit are installed. It is tip-of-tree for this repo: reproduce there, as a test in its 
tests/mcp/cli-*.spec.ts
, with the 
cli
fixture of 
tests/mcp/cli-fixtures.ts
. 
npm run test-playwright-cli
runs those tests. Read its 
AGENTS.md
in full before you write the test. It says how to build, test and lint it. The clone has the full history, without file contents until git needs them, so 
git log
and 
git tag --contains
work there.
The pinned version is older than tip-of-tree. 
npm view playwright-core@<alpha> gitHead
prints the upstream commit that an alpha was built from.
$REPO_DIR
是指南中所述的 
microsoft/playwright-cli
checkout。其中已运行 
npm ci
，并已安装锁定版本的浏览器。CLI 默认使用 runner 镜像中的 Google Chrome。如果缺少 Chrome，请使用 
npx playwright install chrome
安装。该 clone 是浅 clone：在需要历史记录之前，请在其中运行 
git fetch --unshallow --tags origin
。
$PLAYWRIGHT_DIR
是位于 
$REPO_DIR
旁边的 
microsoft/playwright
clone，处于 
main
的最新提交。其中已运行 
npm ci
和 
npm run build
，并已安装 Chromium、Firefox 和 WebKit。它是本仓库对应的 tip-of-tree：应在那里复现问题，并将其编写为 
tests/mcp/cli-*.spec.ts
中的测试，使用 
tests/mcp/cli-fixtures.ts
中的 
cli
fixture。
npm run test-playwright-cli
会运行这些测试。编写测试前，请完整阅读其中的 
AGENTS.md
。该文件介绍了如何构建、测试和 lint。该 clone 拥有完整历史，但文件内容会等到 Git 需要时才获取，因此可以在那里使用 
git log
和 
git tag --contains
。
锁定版本比 tip-of-tree 更旧。
npm view playwright-core@<alpha> gitHead
会输出构建某个 alpha 所对应的上游提交。

Fix in microsoft/playwright

在 microsoft/playwright 中修复

When the fix is in 
$PLAYWRIGHT_DIR
, follow the Fix section of the guide there, in place of 
$REPO_DIR
: create the branch 
fix-<n>
from 
main
in 
$PLAYWRIGHT_DIR
, put the regression test in its 
tests/mcp/cli-*.spec.ts
, build and lint as its 
AGENTS.md
says, and commit in its convention, for example 
fix(cli): ...
. Then leave the proposal in 
$OUTPUT_DIR/upstream-fix/
in place of 
$OUTPUT_DIR/fix/
, with the same files:
  • fix.patch
    : the output of 
    git diff --binary main HEAD
    in 
    $PLAYWRIGHT_DIR
    .
  • pr-body.md
    : as the guide says. The 
    Fixes
    line has the full URL of the issue, 
    Fixes https://github.com/microsoft/playwright-cli/issues/<n>
    , so that the PR closes the issue in this repo.
  • proposal.json
    : as the guide says. Write it last.
The publish job opens the draft PR in 
microsoft/playwright
. The revision workflow of that repo addresses the review. Leave one proposal: 
fix/
or 
upstream-fix/
, not both. Do not change 
package.json
here to pick up the fix. It reaches 
@playwright/cli
with the next roll.
Check the linked PRs in both repos. A PR in 
microsoft/playwright
links this issue with its full URL or as 
microsoft/playwright-cli#<n>
. Search there too: 
repo:microsoft/playwright is:pr "playwright-cli/issues/<n>"
and 
repo:microsoft/playwright is:pr "playwright-cli#<n>"
. A PR there from the team or from 
microsoft-playwright-automation
is a team PR. Verify a PR there in 
$PLAYWRIGHT_DIR
.
Already fixed means that tip-of-tree passes and the pinned version fails. The fix reaches users with the next roll. Find the upstream PR with 
git -C $PLAYWRIGHT_DIR log <gitHead of the pinned alpha>..main -- packages/playwright-core/src/tools
, and name it in the note.
当修复位于 
$PLAYWRIGHT_DIR
时，请遵循指南中的 Fix 一节，并使用 
$PLAYWRIGHT_DIR
替代 
$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
    行应包含 issue 的完整 URL，即 
    Fixes https://github.com/microsoft/playwright-cli/issues/<n>
    ，以便 PR 关闭本仓库中的该 issue。
  • proposal.json
    ：按照指南所述编写。最后再写入此文件。
发布作业会在 
microsoft/playwright
中创建 draft PR。该仓库的 revision 工作流会处理评审意见。只留下一个提案目录：
fix/
或 
upstream-fix/
，不要两者都留。不要修改此处的 
package.json
来引入该修复；它会在下一次 roll 中进入 
@playwright/cli
。
检查两个仓库中关联的 PR。 
microsoft/playwright
中的 PR 可能通过完整 URL 或 
microsoft/playwright-cli#<n>
关联此 issue。也要在那里搜索： 
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。
已经修复是指 tip-of-tree 测试通过，而锁定版本测试失败。该修复会在下一次 roll 中交付给用户。使用以下命令查找上游 PR，并在说明中注明它： 
git -C $PLAYWRIGHT_DIR log <gitHead of the pinned alpha>..main -- packages/playwright-core/src/tools

Published versions

已发布版本

To run a published version, for example the version of the reporter or to bisect, create 
$SCRATCH_DIR/playwright-cli-<n>/<version>/
and run there:
bash
npm init -y
npm i @playwright/cli@<version>
npx playwright-cli --help
The fixtures of the repo are not available there. Run the condensed repro as 
npx playwright-cli
commands, or as a script that spawns them, in that directory. Serve the page from a 
data:
URL or from 
http.createServer()
in the script. Run 
npx playwright-cli close-all
when you are done, so that no daemon stays open.
npm view @playwright/cli@<version> dependencies.playwright-core
prints the alpha of a release. Match a regression to upstream commits with 
git -C $PLAYWRIGHT_DIR log <good gitHead>..<bad gitHead> -- packages/playwright-core/src/tools
.
要运行已发布版本，例如运行 reporter 的某个版本或用于 bisect，请创建 
$SCRATCH_DIR/playwright-cli-<n>/<version>/
并在其中运行：
bash
npm init -y
npm i @playwright/cli@<version>
npx playwright-cli --help
仓库的 fixture 在那里不可用。请在该目录中将精简后的复现步骤作为 
npx playwright-cli
命令运行，或编写脚本启动这些命令。通过 
data:
URL 提供页面，或在脚本中使用 
http.createServer()
。完成后运行 
npx playwright-cli close-all
，确保没有 daemon 保持打开。
npm view @playwright/cli@<version> dependencies.playwright-core
会输出某个 release 所使用的 alpha。使用以下命令将回归问题与上游提交匹配： 
git -C $PLAYWRIGHT_DIR log <good gitHead>..<bad gitHead> -- packages/playwright-core/src/tools

PRs from third parties

第三方 PR

Do not run a PR in this repo that changes 
package.json
, 
package-lock.json
, 
scripts/
, 
.github/
, 
.azure-pipelines/
or 
.claude/
. For a PR in 
microsoft/playwright
, the list in 
$PLAYWRIGHT_DIR/.claude/skills/playwright-triage/SKILL.md
applies.
如果本仓库中的 PR 修改了 
package.json
、
package-lock.json
、
scripts/
、
.github/
、
.azure-pipelines/
或 
.claude/
，不要运行它。对于 
microsoft/playwright
中的 PR，适用 
$PLAYWRIGHT_DIR/.claude/skills/playwright-triage/SKILL.md
中的列表。