mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Agent tools (MCP)

MCP Playwright

Exercise a web journey in a real browser and collect page, console or visual evidence for review.

For frontend engineers, QA workflows, and agents testing web applications end to end.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Chromium and Firefox sessions plus configurable browser groups
  • Accessible page snapshots
  • Interaction and form tools
  • Console and network inspection
  • Screenshots, tracing, and video

First useBasics

  1. Open one permitted application page and verify a harmless interaction.
  2. Use semantic locators and inspect page state.
  3. Capture console, network, and visual evidence before declaring a pass.

Everyday tasksEveryday use

Verify one flow across browser engines

A release-critical interaction must behave consistently in Chromium and Firefox.

  1. Start an isolated browser for each allowed engine and retain their returned IDs.
  2. Create a browser group from those IDs.
  3. Navigate, interact, and assert once against the group.
  4. Inspect the attributed result for each engine and follow up on divergences individually.
  5. Capture comparable artifacts, close the group, and finish the activities.

What you getOne verification sequence produces separately attributable results across the browser matrix.

How to check: Ordered group envelopes, accessible snapshots, assertions, console/network records, and per-browser screenshots or traces.

Capture a responsive evidence pass

A UI change needs rendered, interaction, and diagnostic evidence at multiple viewport sizes.

  1. Start isolated browsers with explicit viewport or device profiles.
  2. Navigate to the real routed application URL.
  3. Inspect semantic page state and exercise the critical interaction.
  4. Check console and network activity alongside screenshots.
  5. Finalize video or trace capture by stopping each browser.

What you getThe review includes behavioral and diagnostic evidence alongside the visuals.

How to check: Viewport-tagged screenshots, accessibility snapshots, console/network results, traces, and finalized video where enabled.

Settings to decideAdvanced

Browser engine allowlist
List only installed engines the server should accept; Chromium and Firefox are the default supported set.
Process paths and timeouts
Set the upstream executable and start/tool timeouts so they fit within the fixed outer call timeout.
Group concurrency
Bound parallel fan-out according to workstation capacity and the size of the intended browser matrix.
Per-browser isolation and state
Choose isolation, permissions, storage state, proxy, viewport, and capture settings per browser instead of relying on ambient state.
Environment forwarding
Extend the subprocess environment allowlist narrowly.
GPU selection
Prefer the surrounding workspace detection, overriding per spawn only when the test requires a deliberate hardware or software path.

CommandsAdvanced

$ mcp-playwright cli browser start chromium
$ mcp-playwright cli browser list
$ mcp-playwright cli navigate to <browser-id> https://example.com
$ mcp-playwright cli page screenshot <browser-id>
$ mcp-playwright cli browser stop <browser-id>

Problems and fixesHelp

What you seeCheckFix
browser_start does not return a browser ID.Inspect allowed engines, executable availability, start timeout, display state, and requested GPU path.Correct the missing runtime prerequisite or start with a supported software-rendered configuration.
A group call succeeds in some browsers and fails in another.Use the attributed browser ID and first error, then inspect that browser alone with snapshot, console, and network evidence.Diagnose the engine-specific rendered state without restarting passing members; rerun the bounded assertion after the fix.
A browser operation ends at the outer timeout.Compare navigation/action settings with the server call ceiling and inspect network or page state for a stalled condition.Narrow the operation, correct the stalled dependency, or use a state-based wait that can complete within the effective timeout.
A captured resource cannot be read.Confirm the resource URI belongs to the current MCP session and that capture completed.Read it from the producing session or recapture; stop the browser first when finalization is required for video.
What you see
browser_start does not return a browser ID.
Check
Inspect allowed engines, executable availability, start timeout, display state, and requested GPU path.
Fix
Correct the missing runtime prerequisite or start with a supported software-rendered configuration.
What you see
A group call succeeds in some browsers and fails in another.
Check
Use the attributed browser ID and first error, then inspect that browser alone with snapshot, console, and network evidence.
Fix
Diagnose the engine-specific rendered state without restarting passing members; rerun the bounded assertion after the fix.
What you see
A browser operation ends at the outer timeout.
Check
Compare navigation/action settings with the server call ceiling and inspect network or page state for a stalled condition.
Fix
Narrow the operation, correct the stalled dependency, or use a state-based wait that can complete within the effective timeout.
What you see
A captured resource cannot be read.
Check
Confirm the resource URI belongs to the current MCP session and that capture completed.
Fix
Read it from the producing session or recapture; stop the browser first when finalization is required for video.

All MCP Playwright problems and fixes →

Good to knowHelp

  • Browser automation validates the rendered behaviour of the page.
  • Each call runs within a fixed 60-second outer time bound.
  • Screenshots, traces and video come back as session artifacts you open.