Playwright CLI

Playwright CLI in Core

Use Playwright CLI as a token-efficient interactive browser driver. Keep Core's committed Playwright Test suites as the regression and CI source of truth.

Boundary

• Use this skill to inspect a running app, reproduce a UI problem, exercise a flow, or gather browser evidence.
• Use docs/ai/skills/playwright-best-practices/SKILL.md when authoring or repairing @playwright/test specs.
• Use docs/ai/skills/accessibility-review/SKILL.md for accessibility review; a CLI snapshot is useful evidence but is not an axe or WCAG audit.
• Do not add @playwright/cli to package.json for one-off agent work. Prefer an available playwright-cli binary; otherwise use a Bun one-off invocation.
• The CLI compares .agents/skills/playwright-cli and .claude/skills/playwright-cli byte-for-byte with its bundled generic skill. Core's repository-adapted skill intentionally differs, so the CLI may print a version-mismatch notice. Do not run its suggested install --skills command; that would overwrite generated mirrors. Refresh the canonical skill and run Core's sync workflow instead.

Start by checking the live command surface:

playwright-cli --help
# If the binary is unavailable:
bunx --bun @playwright/cli@latest --help

Use the same available command prefix for the rest of the session. Help output is authoritative because the CLI evolves independently of Core's pinned @playwright/test package.

Workflow

1. Find the target. Check whether the relevant Core dev server is already running before starting one. Confirm the exact local URL and expected app state; use Next.js devtools when it can answer route/runtime questions.
2. Open and snapshot. Open the route and save a shallow snapshot under ignored test-results/; the CLI's default .playwright-cli/ output would dirty this repository. Use find or a focused element snapshot rather than loading an unnecessarily large page tree.
3. Act through user-facing controls. Prefer snapshot refs or role locators. Refresh the snapshot after navigation or material DOM changes because refs are session state, not durable test selectors.
4. Observe the result. Confirm visible state and URL, then inspect console messages and network requests when the claim depends on runtime behavior. Use tracing only for failures that need a timeline.
5. Capture bounded evidence. Store screenshots, traces, videos, PDFs, and saved auth state only under ignored test-results/ or .auth/ paths. Never print, persist, or commit credentials, cookies, service tokens, or Vercel bypass secrets.
6. Close the session. Close browsers and clean up disposable routes/mocks. If the behavior can regress, convert the proof into a committed Playwright Test spec and run the applicable Core package script.

Compact command set

playwright-cli open http://localhost:3000
playwright-cli snapshot --filename=test-results/playwright-cli/snapshot.yaml --depth=4
playwright-cli find "Sign in"
playwright-cli click e15
playwright-cli fill e21 "demo value"
playwright-cli press Enter
playwright-cli console error
playwright-cli requests
playwright-cli screenshot --filename=test-results/playwright-cli/result.png
playwright-cli close

For multiple roles or apps, use named sessions (-s=<name>) rather than sharing cookies or page state. Prefer demo/test accounts and Core's existing auth helpers. Do not use eval or storage mutation to bypass the behavior being verified; reserve them for narrow inspection or explicitly tested setup.

Checklist

• The task needs live browser interaction rather than a unit test or static read.
• An existing dev server and the exact route were checked first.
• The CLI help for the available version was consulted.
• Interactions use current refs or user-facing locators and verify outcomes.
• Console/network/trace evidence is collected only when relevant.
• Artifacts and auth state stay in ignored paths with no secrets in output.
• The session is closed, and regression-worthy behavior becomes a test.

Provenance

See references/upstream.md for the reviewed official source, Apache-2.0 license, Core adaptations, and refresh workflow.