/api-review

name: api-review
description: Produce the "Playwright 1.xx API Review" artifact for a range of commits - the public API additions and the breaking or behavior changes that affect existing users since the last API review or since the last release, ordered by impact, each with links, before/after snippets and a documentation check. Covers microsoft/playwright (Node.js) and the Python, Java and .NET ports. Use when asked for an API review, to review API changes, or to check what changed in the public API since a release or since the last review.
user_invocable: true

API review

`/api-review [python|java|dotnet] [range]`

Without a language, review microsoft/playwright (the Node.js package, the test runner, MCP and the CLI). With a language, review that port: see "Language ports" at the end, which changes the range, the sources and the composition; everything else applies as written.

Produce one artifact (an HTML page published with the Artifact tool) that a maintainer reads before a release. It lists the changes in the range that **change the public API or affect existing users**, ordered by impact, and checks that each one is documented. The reviewer types feedback into the page and copies a GitHub issue draft from it.

The review is not a changelog. A change is in because a user has to learn a new API, or because an existing test suite may start behaving differently. A fix that makes Playwright more correct in a corner case is not in, even though some user somewhere will notice it.

Work in the current checkout only. Do not commit anything.

1. Choose the range

In order of preference:

1. **Explicit range** from the argument, for example `v1.64.0..main` or `abc1234..main`. 2. **Since the last API review.** List the user's artifacts (`Artifact` tool, `action: "list"`) and take the newest one titled `Playwright 1.xx API Review`. Read it; the `.meta` line records `Range: <base>..main (<n> commits, head <sha>)`. The new range is `<sha>..main`. Use this when the user says "since the last review" or when a review for the current version already exists. 3. **Since the last release.** `git fetch --tags`, then the newest `v1.xx.0` tag (`git tag --sort=-creatordate | grep -v beta | head`). The range is `v1.xx.0..main`. Point releases cherry-pick from main: list `git log --oneline v1.xx.0..v1.xx.y` and exclude those PR numbers, since they are already released. Say so in the `.meta` line.

Read the version under review from `package.json` (`1.65.0-next` means `1.65`).

2. Collect candidates

Run these and keep a list of candidate commits with their PR numbers. Run independent commands in parallel.

• `git log --oneline --no-merges <range>`, dropping `chore(deps`, browser rolls, `devops(`, and

`test(` commits. Everything else is a candidate until it is ruled out.

• `grep -rn -B3 "since: v1.xx" docs/src/` for new API entries.
• `git diff --stat <range> -- docs/src` and then the content diff of `docs/src/test-api`,

`docs/src/test-reporter-api`, the changed guides (`docs/src/*-js.md`, `docs/src/*.md`) and the changed `docs/src/api/class-*.md`. Filter out type-rendering noise (lines that start with `- type:` or `` - `name` ``) to find real text changes.

• Public types: `git diff <range> -- packages/playwright/types/test.d.ts

packages/playwright/types/testReporter.d.ts packages/playwright-core/types/types.d.ts`, keeping only non-comment added or removed lines.

• CLI and MCP options: diff of `packages/playwright/src/program.ts`,

`packages/playwright-core/src/tools/cli-daemon/commands.ts`, `packages/playwright-core/src/tools/mcp/program.ts` and `packages/playwright-core/src/tools/mcp/config.d.ts`.

• Environment variables: grep the range diff for added `process.env.PLAYWRIGHT_` and `PW_` names.
• Reverts: a `Revert "..."` commit of a change that shipped in the last release is a breaking change

against that release. Check with `git merge-base --is-ancestor <original sha> v1.xx.0`.

For each candidate, get the PR body and linked issues in one loop: `gh pr view <n> --repo microsoft/playwright --json title,body,closingIssuesReferences`. Squashed commit messages have no bodies; the PR body is where the rationale and the issue links are. Then `git show --stat <sha> -- docs` tells which docs the PR touched.

3. Decide what is in

Two questions decide it. Does the change add, remove or rename something in the public API? Does it change what existing user tests do, broadly enough that a maintainer would list it under "Breaking Changes" in the release notes? One yes is enough. Two noes and the change is out, however visible.

**Include:**

• New public API: classes, methods, options, events, test and config options, fixtures, reporters

and reporter options, CLI flags and commands, documented environment variables, MCP tools, tool parameters, MCP config and flags, `playwright-cli` commands and options.

• Breaking changes: functionality removed or renamed, defaults changed, a documented behavior changed

so that existing user tests can fail or pass differently. Reverts of behavior that shipped in the last release count, even when the revert restores older behavior.

• Behavior changes that are not bug fixes: a stricter check, a new exit code, a new wait, a changed

output location or format that other tools read.

• A bug fix only when it clears the impact bar: a common pattern in existing tests changes outcome,

for example a passing action now waits and times out, a throwing action now succeeds, or a CI run exits with a different code. Corrections in corner cases do not clear the bar, even when they change observable behavior: cookie matching rules for subdomains, which credentials answer which auth challenge, encoding details, internal browser implementation swaps with an escape hatch.

**Exclude**, and list in "Examined and not included" with the reason:

• Bug fixes that restore documented or intended behavior, including regression fixes and fixe