playwright-cli

Highlights

• install --skills supports the -g flag (microsoft/playwright#42087) — installs the skill into your home directory instead of the current workspace. (microsoft/playwright#42099)
• Generated code in Python, Java and C# (microsoft/playwright-mcp#1696) — code can be generated in Python, Java and C# in addition to JavaScript. (microsoft/playwright#42106)
• Configurable post-action settle delay — tune how long the CLI waits for the page to settle after each action. (microsoft/playwright#41924)

Fixes

• feat(mcp): emit structured snapshot in --json responses — --json no longer wraps formatted text in a string; responses carry a structured page snapshot. (microsoft/playwright#42076, microsoft/playwright#42098)
• feat(mcp): add snapshot.boxes config to include bounding boxes in snapshots — bounding boxes can now be enabled globally via config rather than per snapshot. (microsoft/playwright-mcp#1695, microsoft/playwright#42102)
• fix(cli): exit with non-zero code when the tool result is an error — failed commands no longer exit with status 0, so scripts and agents can detect errors. (microsoft/playwright#42028, microsoft/playwright#42042)
• fix(cli): accept multiple files in upload command — upload no longer rejects a second file although it advertises "one or multiple files". (microsoft/playwright#42047, microsoft/playwright#42057)
• fix(mcp): reconnect to the browser after disconnect — the relay reconnects after the browser extension disconnects. (microsoft/playwright#41874, microsoft/playwright#41966)
• fix(mcp): launch the Chrome profile that has the extension installed — attach no longer targets a different profile than the one with the extension. (microsoft/playwright#41916, microsoft/playwright#41939)
• fix(mcp): pass noDefaults for extension CDP connections — extension connections no longer override existing browser defaults. (microsoft/playwright#42117, microsoft/playwright#42119)
• fix(mcp): clear dialog modal state when dialog is closed out of band — dialogs dismissed by hand in headed mode no longer leave the session stuck in a modal state. (microsoft/playwright#42032)
• fix(mcp): report malformed JSON config instead of falling back to INI — a broken JSON config file now produces a clear error instead of being silently parsed as INI. (microsoft/playwright#41909)
• fix(mcp): surface the missing executable path when a browser isn't installed — clearer error message pointing at the missing browser executable. (microsoft/playwright#41941)
• fix(mcp): identify downloads explicitly — downloads are labeled explicitly in command responses. (microsoft/playwright#41933)
• fix(mcp): validate Host and Origin on CDP relay WebSocket upgrades — hardens the extension relay against unauthorized cross-origin connections. (microsoft/playwright#42103)
• fix(mcp): escape user input in codegen output — special characters in your input are escaped correctly in the generated code. (microsoft/playwright#41962)
• fix(mcp): mention PLAYWRIGHT_MCP_EXECUTABLE_PATH in extension not found error — points at the escape hatch when the extension browser can't be located (e.g. on WSL2). (microsoft/playwright#42092, microsoft/playwright#42122)
• perf(mcp): skip aria snapshot capture when the response discards it — commands that don't need a snapshot run faster. (microsoft/playwright#41923)
• The v0.1.17 fix for goto crashing on privileged pages (chrome://…) was reverted upstream: the crash originates in the browser process itself, and the fix only masked it. (microsoft/playwright#41931)

Fixes

• goto no longer crashes the browser session on privileged pages (#433) — navigating to pages like chrome://extensions/ or chrome://settings/ used to throw TypeError: Cannot read properties of undefined (reading 'url') and take down the whole session. (microsoft/playwright#41675)
• fix(mcp): await init page before screenshot — screenshots taken right after open no longer race the page init. (microsoft/playwright#41646)
• fix(mcp): preserve directory for additional tab videos — videos for extra tabs are saved to the configured output directory. (microsoft/playwright#41680)
• feat(mcp): always pass noDefaults for CDP connections — attaching over CDP no longer applies unwanted default context options. (microsoft/playwright#41676)

Highlights

• Search a large snapshot instead of capturing the whole thing — the new find command searches the page snapshot for text or a regexp and returns just the matching nodes with surrounding context (like grep -C), keeping big pages out of the model context. (microsoft/playwright#41605, microsoft/playwright#41654)
• Mobile emulation — open --mobile emulates a generic mobile device (Pixel for Chromium, iPhone for WebKit) and --device="iPhone 15" targets a specific one; mobile pages are usually lighter, so snapshots are smaller and cheaper. (microsoft/playwright#41657)
• Leaner snapshots — AI snapshots are distilled to be less verbose, cutting token cost on every command that returns page state. (microsoft/playwright#41604)
• Local invocation via npx playwright cli — the CLI is now exposed as playwright cli (and playwright mcp), so a locally installed Playwright can drive it without a separate global install. (microsoft/playwright#41577)

Fixes

• feat(mcp): surface non-2xx navigation status — navigation now reports the HTTP status instead of silently succeeding on error responses. (microsoft/playwright#41589)
• fix(mcp): enable the chromium sandbox for the default browser — the default Chromium browser now runs sandboxed. (microsoft/playwright#41652)
• fix(routing): normalize literal glob components through new URL() — route patterns with literal glob characters now match reliably. (microsoft/playwright#41682)
• fix(mcp): close isolated HTTP client context on disconnect — isolated sessions release their context cleanly on disconnect. (microsoft/playwright#41560)

Highlights

• High resolution screenshots (#376) — playwright-cli screenshot --hires captures at the device's full pixel ratio instead of downscaling to CSS pixels. (microsoft/playwright#41465)
• Secrets filtered from console logs (#41509) — configured secret values are now redacted in captured console log artifacts. (microsoft/playwright#41515)

Heads up

• The CLI now checks for updates — on startup it notifies you when a newer @playwright/cli is available on npm. (#426)
• The CLI now warns when your installed skill is out of date — if the bundled Playwright skill is newer than the one installed in your workspace, you'll be prompted to reinstall it. Re-run playwright-cli install --skills to update. (#427)

Fixes

• fix(mcp): pass action timeout to browser_wait_for waitFor calls — wait_for now honors the configured action timeout instead of waiting indefinitely. (microsoft/playwright#41270)
• fix(mcp): wait for next pause or context closure in browser_resume — resuming a paused session settles reliably. (microsoft/playwright#41293)
• fix(mcp): assign caps as array for legacy --vision flag — the legacy --vision flag works again. (microsoft/playwright#41253)
• fix(mcp): never include data: URL payloads in snapshot or network output — large data: URLs no longer flood snapshot and network output. (microsoft/playwright#41450)
• fix(mcp): list a failed network request only once — failed requests are no longer duplicated in network output. (microsoft/playwright#41481)
• fix(mcp): check tracing state before stopping in browser_stop_tracing — stopping tracing when it is not running no longer errors. (microsoft/playwright#41040)
• fix(mcp): add missing .catch() on sessionLog write queue — a failed session-log write no longer crashes the session. (microsoft/playwright#41234) (microsoft/playwright#41382)

Highlights

• Annotate actions in recorded videos — new video-show-actions / video-hide-actions commands draw a callout naming each action and highlighting its target in the recording. (microsoft/playwright#40914)
• exposeNetwork and other connect options for remote browsers — remoteEndpoint now accepts a full ConnectOptions object, so settings like exposeNetwork and headers apply to remote connections. (microsoft/playwright#40964)
• Bounded output size — --output-max-size caps captured output and evicts to disk after the response, keeping large sessions manageable. (microsoft/playwright#41031)

Fixes

• fix(cli): support attaching to a Playwright browser server endpoint (microsoft/playwright#41154) — playwright-cli attach --endpoint=<ws-url> connects to a running browser server instead of erroring out. (microsoft/playwright#41203)
• fix(mcp): support moz-firefox BiDi channels via --browser — connect to Firefox over BiDi using --browser. (microsoft/playwright#41126)
• fix(mcp): keep remoteHeaders working for remote browser endpoint — custom headers are sent again when connecting to a remote endpoint. (microsoft/playwright#41156, #40828)
• fix(cli): persist traces when CLI attaches to existing CDP browser — traces are now saved when attaching over CDP. (microsoft/playwright#40810)
• fix(cli): accept single --modifiers value for click and dblclick — --modifiers=Shift works without requiring a list. (microsoft/playwright#40784)
• fix(cli): trim overlong session names to fit unix socket path limit — long session names no longer break the daemon socket. (microsoft/playwright#40898)
• fix(cli): do not pass PLAYWRIGHT_CLI_SESSION as daemon --endpoint — fixes spurious endpoint resolution from the session env var. (microsoft/playwright#41019)
• fix(mcp): report missing ffmpeg distinctly from missing browser — clearer error when video recording fails due to a missing ffmpeg. (microsoft/playwright#40867)
• fix(mcp): report invalid tool arguments — invalid arguments now produce a readable error instead of failing silently. (microsoft/playwright#40979)
• fix(mcp): use writable cache dir for MCP user data, not browsers path — avoids permission errors on read-only browser installs. (microsoft/playwright#40961)
• fix(mcp): use waitUntil commit for navigate back/forward — back/forward navigation resolves more reliably. (microsoft/playwright#41153)
• fix(mcp): tear down dashboard server on cli show --kill — cli show --kill fully stops the dashboard. (microsoft/playwright#40968)
• fix(tracing): mkdir tracesDir before live .stacks writes — fixes a crash when the traces directory does not yet exist. (microsoft/playwright#40730)
• docs(cli): document & URL escaping on Windows — guidance on escaping & in URLs on cmd.exe and PowerShell. (microsoft/playwright#40742)

Upgrading

npm install -g @playwright/cli@0.1.14

Fixes

• fix(mcp): forward browser-level CDP commands in extension mode — cookie-list, state-save, and other browser-scoped commands now work when attached via the Chrome extension. (microsoft/playwright#40706)

Highlights

• Chrome extension now supports multiple tabs (#373 — tab-new, tab-list, etc. work in attach --extension sessions.

• Multi-screenshot UI Review in the dashboard — collect, annotate, and submit several screenshots in one dashboard session, with a sidebar of frames and per-comment highlight.

Fixes

• fix(mcp): recover from page renderer crash — the current tab is reopened automatically when its renderer crashes. (microsoft/playwright#40617)
• fix(mcp): auto-recover when remote browser disconnects mid-session — the next tool call transparently reconnects. (microsoft/playwright#40652)
• fix(mcp): anchor aria-ref regex in target resolution — locators with e\d+ substrings are no longer misclassified. (microsoft/playwright#40610)
• fix(mcp): skip base64 image when filename is provided — explicit-filename screenshots no longer also embed the image in the response. (microsoft/playwright#40577)

Fixes

• fix(dashboard): handle null viewport in annotate screenshot — playwright-cli annotate against a headed browser launched with viewport: null produced an empty annotated screenshot; the dashboard now falls back to window.innerWidth/innerHeight. (microsoft/playwright#40569)

Highlights

• Network inspection split into numbered commands (#377) — network is replaced with:

  • requests — numbered list of requests with stable indexes
  • request <num> — full details for one request
  • request-headers <num>, request-body <num>, response-headers <num>, response-body <num> — pipe-friendly part extractors

  Bodies are no longer inlined; pass --filename on any part-command to save the result to a file. (microsoft/playwright#40447, microsoft/playwright#40454)

• Spec-driven testing skill — a new references/spec-driven-testing.md reference guides agents through a plan / generate / heal workflow for driving Playwright tests from a written spec. (microsoft/playwright#40460)

Behavior changes

• Read-only data-fetching commands (cookie-list, cookie-get, localstorage-list, localstorage-get, sessionstorage-list, sessionstorage-get, route-list, request-headers, request-body, response-headers, response-body) now emit raw output by default — no more ### Result wrapper, no --raw needed. (microsoft/playwright#40473)
• Extension mode now ignores the browser section of any loaded config file (both userDataDir and executablePath); only the browser/channel from --browser or PLAYWRIGHT_MCP_BROWSER applies. (microsoft/playwright#40475)
• requests now appends a hint when static requests are filtered out, telling the user to pass --static to see them. (microsoft/playwright#40454)

Fixes

• fix(cli): resolve initPage/initScript paths and surface load errors (#290) — relative initPage / initScript paths from --config files now resolve against the config dir (matching Vite/Vitest/ESLint), and CLI-flag / env-var entries resolve against cwd. Load errors are no longer silently swallowed. (microsoft/playwright#40451)
• fix(mcp): detect extension in non-default Chrome profiles — the --extension preflight now scans every Profile * subdirectory under the user data dir, not just Default. (microsoft/playwright#40471)
• fix(mcp): surface unhandled rejections instead of crashing the server — async errors from user-installed callbacks (e.g. a page.route handler) are now reported on the next tool response instead of tearing down the MCP transport. (microsoft/playwright#40452)

Highlights

• show --annotate — provide agent with visual and structural feedback while developing or testing. (microsoft/playwright#40262, microsoft/playwright#40238)

• drop command for files and clipboard-like data — drop files or typed data (text/plain, text/html, etc.) onto an element from outside the page. Useful for file-upload widgets and drag-from-desktop scenarios where upload doesn't fit. (microsoft/playwright#40367, microsoft/playwright#40283)

• highlight command for visual confirmation — show a persistent highlight overlay on an element (with optional custom CSS via --style), and hide one or all overlays with --hide. Lets coding agents visually confirm what they're about to act on. (microsoft/playwright#40213, microsoft/playwright#40215, microsoft/playwright#40219)

• generate-locator command — produce a stable Playwright locator expression for an element ref. Pair with --raw to feed locators straight into test assertions. (microsoft/playwright#40313)

• --json global flag — wrap every reply as structured JSON for machine parsing. (microsoft/playwright#40284)

  > playwright-cli eval --json "document.body.childNodes.length"
  {
    "result": "4"
  }
  

• snapshot --boxes — include each element's bounding box as [box=x,y,width,height] in aria snapshots, making it easy to drive coordinate-based tools off of a snapshot. (microsoft/playwright#40389)

  - paragraph [ref=e35] [box=86,381,700,99]:
    - text: One API to drive Chromium, Firefox, and WebKit — in your tests, your scripts...
    - link "TypeScript" [ref=e36] [cursor=pointer] [box=535,417,98,27]:
      - /url: https://playwright.dev/docs/intro
    - text: ","
    - link "Python" [ref=e37] [cursor=pointer] [box=644,417,66,27]:
      - /url: https://playwright.dev/python/docs/intro
    - text: ","
    - link ".NET" [ref=e38] [cursor=pointer] [box=721,417,42,27]:
      - /url: https://playwright.dev/dotnet/docs/intro
    - text: ", and"
    - link "Java" [ref=e39] [cursor=pointer] [box=127,450,38,27]:
      - /url: https://playwright.dev/java/docs/intro
  

• Discover attachable system browsers with list --all — surfaces Chrome/Edge instances running with remote debugging so attach --cdp=<channel> has something to connect to. (microsoft/playwright#40253, microsoft/playwright#40342)

• detach command and channel-named attach sessions — attach sessions now use the channel name (e.g. chrome, msedge) and can be cleanly detached without closing the underlying browser. (microsoft/playwright#40408)

• Skill discoverable from --help — playwright-cli --help now prints the path to the installed agent skill, so coding agents can find it without being told. (microsoft/playwright#40274)

• run-code accepts a file — playwright-cli run-code --filename=./script.js runs a Playwright snippet from disk instead of the command line. (microsoft/playwright-cli#337)

Behavior changes

• attach now requires an explicit target; bare attach is no longer allowed. (microsoft/playwright@f7555ef)
• The "Playwright MCP Bridge" extension has been renamed to "Playwright Extension", and the CLI now warns when the extension is missing from the target profile. (microsoft/playwright#40259, microsoft/playwright#40406)
• CLI option names have been tidied up to be friendlier for Claude Code and other agents. (microsoft/playwright#40369)

Fixes

• fix(cli): exit daemon when extension connection fails — no more orphaned daemons when the browser extension can't connect. (microsoft/playwright#40328)
• fix(cli): prefix bare filenames with ./ in printed links — output file links now open reliably in terminals and editors. (microsoft/playwright#40311)
• fix(cli): show "(no browsers)" when list is empty without --all — clearer empty-state output from list. (microsoft/playwright#40277)
• fix(mcp): disable CDP timeout for extension connection — long-running extension attaches no longer time out. (microsoft/playwright#40265)
• fix(mcp): support page close via extension in protocol v2 — closing tabs through the extension works again. (microsoft/playwright#40249)
• fix(mcp): throw clear error for tab creation in extension protocol v1 — replaces a cryptic failure with a readable message. (microsoft/playwright#40261)
• fix(mcp): ensure --proxy-server overrides config-file proxy — explicit CLI proxy now wins over the config value. (microsoft/playwright#40212)
• fix(server): close browsers when PlaywrightServer shuts down — cleaner shutdown, no lingering browser processes. (microsoft/playwright#40294)

Upgrading

npm install -g @playwright/cli@latest

Highlights

• Remote debugging mode against your local Chrome (#358) — you can now drive the Chrome you already have open, with its existing logins, instead of a sandboxed copy. playwright-cli attach --cdp=chrome (also msedge, chrome-canary, etc.) resolves the channel and connects via chrome://inspect/#remote-debugging. Supports Chrome / Chrome Beta / Dev / Canary and Edge / Edge Beta / Dev / Canary on Linux, macOS, and Windows. (microsoft/playwright#40177)
• Heavy CPU/memory and orphaned Chrome processes (#360) — no more manually killing leftover Chrome processes after long CLI/agent sessions. (microsoft/playwright#40190)

Fixes

• fix(mcp): no tombstones on the server registry level — defaults browserToken to 'chrome' when none is specified (no more undefined in userDataDir paths); simplifies stale-entry cleanup in the server registry; passes force to session stop during delete-data. (#40179)

Upgrading

npm install -g @playwright/cli@0.1.8