Use when the agent needs to drive a browser through the Microsoft Playwright CLI (playwright-cli) for navigation, form interactions, screenshots, recordings, data extraction, session management, or debugging without loading a full MCP browser. It trains the agent on the CLI commands, snapshots, and session/config habits that make Playwright CLI reliable for scripted browsing.
The CLI is headless by default; add --headed to open or set browser.launchOptions.headless to false in playwright-cli.json when you need to see the UI.
The CLI reads playwright-cli.json by default or whatever file you pass with --config. Use the config to tune browser name, launch/context options, viewport, timeouts, output directories, and recording settings without changing every command.
Keep playwright-cli --help terminal-accessible; the script self-documents the latest commands and options so you can refresh your memory before trying a new action.
Core interaction loop
Start with playwright-cli open <url> to load the page (add --session=name if you want isolation up front).
Run playwright-cli snapshot to generate element refs (e1, e2, …) before any interaction. Always re-snapshot after DOM changes or navigation to avoid stale refs.
Append [button], [value], or JS snippets as needed (e.g., playwright-cli click e4 right).
Capture output evidence with screenshot [ref], pdf, console [level], or network to prove the flow or inspect errors.
Example flow:
bash
playwright-cli open https://example.com/login
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "supersecret"
playwright-cli click e3
playwright-cli snapshot
playwright-cli screenshot
Sessions & persistence
Use --session=<name> to keep cookies, storage, and tabs isolated per workflow. Sessions behave like persistent profiles: they remember auth state, history, and tabs between commands.
Export PLAYWRIGHT_CLI_SESSION=mysession if you are running many commands in the same session — the CLI will default to that session without needing --session each time.
Use playwright-cli --isolated open ... for ephemeral contexts that do not persist to disk.
Whenever you change browser settings for a session (launch args, headless toggle, browser selection), rerun playwright-cli config for that session and then session-restart to apply the new config.
If a command fails, rerun playwright-cli snapshot to confirm refs are still valid. Snapshots provide the current DOM context for click/type operations.
playwright-cli --help always shows the latest command set, so consult it before trying a rarely used flag.
When the agent needs to replicate a recorded manual flow, capture a screenshot, note the session name, and mention which refs and tabs were in use.
If targeting a visible browser is required (e.g., manual inspection), reconfigure with --headed, or run playwright-cli open --headed <url> for that session only.