| name | playwright-cli |
| description | Use Playwright CLI for ad hoc browser automation and interactive verification of Core UI: opening local routes, navigating, inspecting snapshots, using element refs, checking console/network activity, capturing evidence, tracing, and reproducing flows. Do not use it as a substitute for committed `@playwright/test` coverage or for non-browser unit tests. |
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
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
Provenance
See references/upstream.md for the reviewed official
source, Apache-2.0 license, Core adaptations, and refresh workflow.
