| name | playwright-cli |
| description | Capture browser screenshots for visual design verification (DESIGN.md Verification Gate). Use when a UI change needs an actual rendered screenshot — de-gradient passes, layout/spacing checks, light/dark comparison — rather than a static class diff. Covers the managed/remote-env quirks (browser install via resumable download, full-chrome headless launch, localhost-only page loads). |
Playwright CLI — visual verification
Turns "I can't see it headless" into a real screenshot. Use it to satisfy the
DESIGN.md Verification Gate with rendered evidence instead of inferring from
class diffs.
One-time setup (per fresh environment)
The managed/remote container ships an older Chromium than @playwright/test
needs, and npx playwright install is cut mid-download by the egress proxy.
The setup script works around it with a resumable download:
bash scripts/setup-playwright.sh
Idempotent — exits early if the right Chromium revision is already runnable.
After it runs, chromium.executablePath() resolves to a working full-Chrome
build under $PLAYWRIGHT_BROWSERS_PATH.
Taking a screenshot
node scripts/screenshot.mjs http://localhost:3000/ shots/landing.png 1440 900
node scripts/screenshot.mjs http://localhost:3000/dashboard shots/dash.png --both
Then view the PNG (Read tool on the file) — looking at it is the point.
Hard environment limits (read before screenshotting a URL)
When NOT to use this
- Pure class-token swaps already covered by
rg/eslint static checks — a
screenshot adds nothing.
- Anything requiring a remote URL with no local run path — fall back to the
Vercel preview deploy + human review (document that you couldn't screenshot).
Companion: Playwright MCP
.mcp.json registers @playwright/mcp for interactive browser-driving tools
(navigate, click, snapshot) in future sessions. It loads at session start,
so it is not available in the session that adds it — restart to pick it up. It
inherits the same localhost-only network limit above.