From c141f97e53318c880f3436d15eb8e2cd1c1f56c0 Mon Sep 17 00:00:00 2001 From: Pavel Feldman Date: Tue, 10 Nov 2026 08:19:50 -0800 Subject: [PATCH] docs: say in AGENTS.md how this repo depends on Playwright The playwright-triage skill goes away. What it said about this repo is in AGENTS.md now: where the code is, what this repo owns, the pin, and where a fix goes. --- .claude/skills/playwright-triage/SKILL.md | 86 ----------------------- AGENTS.md | 31 ++++++-- 2 files changed, 24 insertions(+), 93 deletions(-) delete mode 100644 .claude/skills/playwright-triage/SKILL.md diff --git a/.claude/skills/playwright-triage/SKILL.md b/.claude/skills/playwright-triage/SKILL.md deleted file mode 100644 index 9c8550de..00000000 --- a/.claude/skills/playwright-triage/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: playwright-triage -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 - -## 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. - -## Reproduce on tip-of-tree - -The pinned alpha is older than tip-of-tree. `npm view playwright-core@ gitHead` prints the -upstream commit that an alpha was built from. - -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 CLI uses Google Chrome by default. When it is missing, install it with -`npx playwright install chrome`. - -## Fix in microsoft/playwright - -When the cause is upstream, fix it in `../playwright`: create the branch `fix-` 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/`: 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. - -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 `. 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 `. 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#`. Search there too: -`repo:microsoft/playwright is:pr "playwright-cli/issues/"` and -`repo:microsoft/playwright is:pr "playwright-cli#"`. A PR there from the team or from -`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 log ..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 an empty -directory outside the repo for each version, and run there: - -```bash -npm init -y -npm i @playwright/cli@ -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@ dependencies.playwright-core` prints the alpha of a release. -Match a regression to upstream commits with -`git -C ../playwright log .. -- 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/.claude/skills/playwright-triage/SKILL.md` applies. diff --git a/AGENTS.md b/AGENTS.md index 65aab324..b9bfaf3d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,27 @@ -## Build and test +## How this repo depends on Playwright + +This repo ships the npm package `@playwright/cli`. The CLI itself 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. + +- **What this repo owns:** `playwright-cli.js`, which runs the CLI of the pinned `playwright-core` + and adds the update check, `skillCheck.js`, the README, and the tests of the packaged CLI. +- **What is a copy:** `skills/playwright-cli/` is a copy of + `packages/playwright-core/src/tools/skills/playwright-cli/`. `node scripts/update.js` refreshes + it on a roll. Change it upstream. +- **The pin:** `package.json` pins an alpha of `playwright` and `playwright-core`. + `npm view playwright-core@ gitHead` prints the upstream commit of an alpha, and + `npm view @playwright/cli@ dependencies.playwright-core` prints the alpha of a release. + The pin is older than the tip of upstream `main`. +- **Where a fix goes:** most bugs and features are upstream. Work in a checkout of + `microsoft/playwright` next to this repo, `../playwright`, as its `AGENTS.md` says. The tests of + the CLI are its `tests/mcp/cli-*.spec.ts`, with the `cli` fixture of `tests/mcp/cli-fixtures.ts`, + and `npm run test-playwright-cli` runs them. Fix here only what this repo owns. +- **How a fix arrives:** with a roll, after `playwright@next` has the upstream commit. The upstream + PR says `Refs ` for an issue of this repo, and the roll PR here says `Fixes`. -The CLI source lives in `microsoft/playwright`, in `packages/playwright-core/src/tools/`. This repo -ships `@playwright/cli`: `playwright-cli.js` runs the CLI of the `playwright-core` alpha that -`package.json` pins, and adds the update check, with `skillCheck.js`. `skills/playwright-cli/` is a -copy of the skill that `playwright-cli install --skills` writes, and `node scripts/update.js` -refreshes it. +## Build and test ```bash npm ci @@ -58,7 +75,7 @@ The Playwright bot does the work below. It opens pull requests as the `microsoft-playwright-automation` app. [triage.yml](.github/workflows/triage.yml) and [review.yml](.github/workflows/review.yml) hand it the labels: -- `agent-triage` on an issue: finds the cause and fixes the issue if it can, with the skill in [.claude/skills/playwright-triage/](.claude/skills/playwright-triage/SKILL.md). A fix in `microsoft/playwright` opens as a draft PR there. +- `agent-triage` on an issue: finds the cause and fixes the issue if it can. A fix in `microsoft/playwright` opens as a draft PR there. - `agent-implement` on an issue: implements what the issue and the maintainers' comments say. - `agent-task` on an issue: does what the issue asks, with the skills of this repo. - `agent-review` on a PR: revises the PR, as the maintainers' review comments say.