playwright-triage

Playwright Issue Triage

Triage a GitHub issue by working out what it actually is, then doing the right thing for that kind. The goal is a clear, verified status, not a fix.

First, classify the issue

Judge by the content, not the label — a "[Feature]" is often really a bug (something already should work), and a "[Bug]" is sometimes expected behaviour. Work out what it actually is:

• Bug — reproduce it. The bulk of this skill.
• Feature request — nothing to reproduce. Check it doesn't already exist (search docs/API, maybe under another name), verify any source the reporter cites by reading it, and surface the real design question. If it's small and well-scoped (like "fail loudly instead of silently"), the ideal takeaway is an acceptance test: one self-contained spec asserting current behaviour (passes today) with the desired behaviour alongside as a fixme/commented assertion.
• Upstream / environment — a genuinely external owner (the Node project, a browser engine, a website's own server/cert config), not Playwright. Find the real owner, don't brute-force a repro, verify any cited upstream issue and point at the real fix path. Note: the Playwright family — @playwright/mcp (source lives here under packages/playwright-core/src/tools/mcp/), playwright-vscode, -python, -java, -dotnet — is not "upstream"; it's us. Never tell a reporter to refile within the project (see below).
• Question / usage — answer it or point at the docs.

The rest of this skill is the bug path.

Reproducing a bug

You're not in a hurry, so be exhaustive before giving up. If the user has provided a minimal repro, try it first. If it does not repro for you, play around with things they might have forgotten to mention: all three browsers, headed/headless, a few recent versions, and variations of the snippet or trigger. Report "cannot reproduce" only after you've genuinely explored — and say what you tried. If you have a hunch for what information would help, ask for it.

Run across browsers, and watch for divergence — a bug that only reproduces in webkit, or everywhere except firefox, is a strong signal worth leading with. Plenty of bugs are browser-agnostic, though, and those are just as real: reproducing on every browser is a good result to report, not a non-finding.

1. Read the whole thread, comments included — the missing repro or narrowed trigger is often there.
2. Pull the inputs: version, browser(s), OS, repro repo/snippet, Expected-vs-Actual (your oracle). If something's missing, guess and try anyway; note assumptions in the report.
3. Reproduce on tip-of-tree first, in ~/tmp/issue-<number>/: clone the linked repo, or scaffold npm install @playwright/test@next with a single-project config (see bisect-published-versions.md). Use PLAYWRIGHT_HTML_OPEN=never. If it reproduces on ToT, it's a live bug — record the exact version/sha you tested, and if it looks like a regression, bisect it (see the guide).
4. If ToT doesn't reproduce it, try the version the user reported. If it reproduces there but not on ToT, it's already fixed — find the version/PR that fixed it (a cherry-pick may still be worth it). If neither reproduces, it's incomplete or env-specific — say what you couldn't match. (A version ending in -next, e.g. 1.62.0-next, is not an npm version — it means tip-of-tree, which is the @next build you already tried.)
5. If ToT does reproduce it - search for related reports. Check the issue timeline for cross-references first. Use GitHub MCP issue and pull request search tools, not gh in CI, and limit this to a handful of searches. Search open and closed issues and PRs with queries such as repo:microsoft/playwright "exact error string" and repo:microsoft/playwright <API name> <trigger>. Also search the relevant family repos: microsoft/playwright-python, microsoft/playwright-java, microsoft/playwright-dotnet, and microsoft/playwright-vscode. Read useful matches and linked changes, including maintainer decisions and follow-up reports. Compare the API usage, trigger, versions, and behavior, not just titles. Check whether an existing API or option actually meets the reporter's goal rather than avoiding the failing operation. If the existing evidence establishes a duplicate or a shipped fix for the reporter's conditions, report that status without repeating the reproduction.

To step through a test interactively, use the playwright-cli skill.

Reports sometimes target another part of the Playwright project — @playwright/mcp (its source is in this repo), playwright-vscode, playwright-python, playwright-java, playwright-dotnet. These are all us, so triage them like anything else: check out that repo and reproduce there in its own language/toolchain when needed. Never tell the reporter the issue belongs in a different Playwright repo or should be refiled there — that's an internal routing detail, not the reporter's problem.

Condense the repro into a self-contained test

Big or app-specific repros are much more useful boiled down to a single self-contained spec, written the way our tests are: one test(...) using the page and server fixtures, tagged with the issue link. Crucially:

• No test.beforeAll / afterAll, no http.createServer, no manual setup/teardown. The fixtures already give you a page and a web server. Use server.setRoute(...), server.setRedirect(...), server.PREFIX, server.EMPTY_PAGE instead of standing up your own.
• Drive the page with page.setContent(...) or page.goto(server.PREFIX + '/...').
• Keep only what's needed to trigger the bug, and end on the assertion that fails.

Drop it into the repo (tests/page/) and run it with npm run ctest.

Mirror real self-contained tests, e.g.:

• tests/page/page-network-request.spec.ts — should return event source: server.setRoute SSE endpoint, no lifecycle hooks
• tests/page/selectors-css.spec.ts — should use light DOM structure for child combinator with slotted content: page.setContent with inline shadow DOM (#37768)
• tests/page/workers.spec.ts — should report worker script as network request after redirect: server fixture with routes/redirects + a browser-gap fixme (#35678)

Verify related fixes

For a related PR, check whether it is open, closed without merging, or merged, and whether the fix has shipped and in which version. Run the condensed repro against the PR branch when available, recording the exact commit and result. If the fix has shipped, verify the repro on that release too. Report anything you could not verify rather than treating an open or merged PR as proof of a fix.

Report

Give a status that fits the issue type — for a bug: reproduced / fixed-on-latest / cannot-reproduce / not-a-bug / duplicate of #N; for a feature request or upstream/env issue: a short verdict (already-possible, valid request, upstream — owned by X) — plus the evidence. For bugs, include the condensed repro and be exhaustive about what you ran — the full matrix of browsers, versions, and variations you tried, not just the one that worked — so the reader can trust the verdict and skip re-checking. Call out any browser-specific divergence. Write it in the Playwright bot voice (.github/workflows/bot-voice.md, relative to the repo root) — maintainer voice, not AI-speak.

Watch out

• Only run code you trust — skim a linked repo/snippet first; bail and report that in the issue comment if it has postinstall scripts, obfuscated code, or random small libraries.
• Triage ends at a reproduction and a status; don't jump to a fix.