Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 29 additions & 59 deletions .claude/skills/playwright-triage/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,10 @@
---
name: playwright-triage
description: Triage and fix one microsoft/playwright-cli issue, or do a maintainer's task, unattended inside the Issue triage GitHub Actions workflow (.github/workflows/triage.yml), which a needs-triage, needs-triage-mac or needs-triage-win label starts, or a maintainer starts by hand with an issue, a task or both. Reproduces the issue on the runner, then leaves a verified fix proposal for the workflow to open as a draft PR, in this repo or in microsoft/playwright where the source of the CLI is, or an investigation note for it to post on the issue. Only for that workflow.
description: Triage and fix an issue in microsoft/playwright-cli. Where the code of the CLI is, how to reproduce on tip-of-tree in microsoft/playwright, where a fix goes, how to run a published version, and what not to run from a PR of a third party.
---

# Playwright CLI Issue Triage

You run unattended in the [Issue triage](../../../.github/workflows/triage.yml) 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](https://github.com/microsoft/playwright/blob/main/.github/actions/run-agent/guides/triage.md),
and then [CLAUDE.md](../../../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`.

## Where the code is

This repo is the npm package `@playwright/cli`: `playwright-cli.js` with its update check,
Expand All @@ -27,72 +19,50 @@ Fix a bug here only when the cause is in a file that this repo owns. `skills/pla
copy of `packages/playwright-core/src/tools/skills/playwright-cli/`, which `scripts/update.js`
refreshes on a roll, so its fix is upstream too.

## The checkouts
## Reproduce on tip-of-tree

`$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.
The pinned alpha is older than tip-of-tree. `npm view playwright-core@<alpha> gitHead` prints the
upstream commit that an alpha was built from.

`$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.
Reproduce in a checkout of `microsoft/playwright` at the tip of `main`, next to this repo, in
`../playwright`. Write the repro 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 pinned version is older than tip-of-tree. `npm view playwright-core@<alpha> gitHead` prints the
upstream commit that an alpha was built from.
The CLI uses Google Chrome by default. When it is missing, install it with
`npx playwright install chrome`.

## Fix in 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/`:

- `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.

Add the `pull-request` call for `microsoft/playwright` last, as the guide says:

```json
{
"call": "pull-request",
"repo": "microsoft/playwright",
"branch": "triage/playwright-cli-<issue>/<run id>-<run attempt>",
"title": "fix(cli): description",
"patch": "upstream-fix/fix.patch",
"bodyFile": "upstream-fix/pr-body.md",
"commitBody": "Fixes: https://github.com/microsoft/playwright-cli/issues/<n>"
}
```
When the cause is upstream, fix it in `../playwright`: create the branch `fix-<n>` from `main`, 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): ...`. The PR there says
`Refs https://github.com/microsoft/playwright-cli/issues/<n>`: the issue stays open until this repo
rolls to the fix. Open one PR, here or in `microsoft/playwright`, not both. Do not change
`package.json` here in the same change.

The publish job checks out `microsoft/playwright` at the commit of `$PLAYWRIGHT_DIR` and opens the
draft PR there. The revision workflow of that repo addresses the review. Make one `pull-request`
call: in this repo or in `microsoft/playwright`, not both. Do not change
`package.json` here to pick up the fix. It reaches `@playwright/cli` with the next roll.
After the upstream PR merges, the fix reaches this repo with a roll. Check that `playwright@next`
has it:
`git -C ../playwright merge-base --is-ancestor <fix commit> <gitHead of playwright-core@next>`. If
it has the fix, roll this repo to it, as [roll.md](../dev/roll.md) says, and add a test here when
the tests of this repo can cover the issue. That PR says `Fixes <issue url>`. If it does not have
the fix yet, the next alpha brings it.

**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`.
`microsoft-playwright-automation` is a team PR. Verify a PR there in `../playwright`.

**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.
`git -C ../playwright log <gitHead of the pinned alpha>..main -- packages/playwright-core/src/tools`,
and name it.

## 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:
To run a published version, for example the version of the reporter or to bisect, create an empty
directory outside the repo for each version, and run there:

```bash
npm init -y
Expand All @@ -107,10 +77,10 @@ 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`.
`git -C ../playwright log <good gitHead>..<bad gitHead> -- packages/playwright-core/src/tools`.

## PRs from third parties

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.
`../playwright/.claude/skills/playwright-triage/SKILL.md` applies.
69 changes: 0 additions & 69 deletions .github/workflows/bots.yml

This file was deleted.

Loading
Loading