playwright mcp

27 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Playwright MCP server overview

The Playwright MCP server provides browser automation capabilities through the Model Context Protocol, enabling LLMs to interact with web pages using structured accessibility snapshots. It works with VS Code, Cursor, Windsurf, Claude Desktop, and other MCP clients without requiring vision models.

Playwright MCP Node.js requirement

Node.js 20 or newer is required to use the Playwright MCP server.

Playwright MCP standard installation configuration

Add Playwright MCP to an MCP client by configuring it in the mcpServers section with command 'npx' and args ['@playwright/mcp@latest'].

Playwright MCP accessibility snapshots

Playwright MCP operates on the page's accessibility tree, not pixels. When a tool runs, it returns a structured snapshot showing page elements, their roles, and text content. Elements have element references that LLMs use to interact with the page.

Playwright MCP browser interactions

Playwright MCP provides tools for navigation (opening URLs, back/forward, reload), clicking and typing (clicking elements, typing text, filling forms, selecting dropdowns), screenshots (capturing page or specific elements), keyboard and mouse actions (pressing keys, hovering, dragging), dialogs (accepting or dismissing), and tabs (creating, closing, switching).

Playwright MCP browser_run_code_unsafe tool

The browser_run_code_unsafe tool executes arbitrary Playwright scripts directly in the Playwright server process. This tool is RCE-equivalent and should only be enabled for trusted MCP clients.

Playwright MCP network monitoring and mocking

Playwright MCP supports inspecting network traffic, listing all requests made since page load, mocking routes with URL pattern matching to return custom responses, and accessing browser console output for debugging.

Playwright MCP storage state management

Playwright MCP can save and restore browser state including cookies and localStorage, allowing persistence of authentication and session data to a file and restoration into new sessions. Individual cookies can be listed, retrieved, set, and deleted.

Playwright MCP headed mode default

By default, Playwright MCP runs the browser in headed mode so you can see what is happening. To run headless, pass the --headless flag in the args.

Playwright MCP browser selection configuration

Browser selection is configured by passing --browser=[browser-name] in the args. Supported values are: chrome, firefox, webkit, msedge.

Playwright MCP user profile modes

Playwright MCP supports three profile modes: Persistent (default) where login state and cookies are preserved between sessions and stored in ms-playwright/mcp-{channel}-{workspace-hash} in the platform's cache directory with automatic separation for different projects, which can be overridden with --user-data-dir; Isolated where each session starts fresh by passing --isolated flag and initial state can be loaded with --storage-state; and Browser extension mode which connects to existing browser tabs with the Playwright Extension by passing --extension flag.

Playwright MCP configuration file

For advanced configuration, use a JSON config file by passing --config path/to/config.json. The config file supports browser options, context options, network rules, timeouts, and more. The full schema is available in the Playwright MCP repository at github.com/microsoft/playwright-mcp/blob/main/config.d.ts.

Playwright MCP standalone server with HTTP transport

Start the MCP server separately with HTTP transport using npx @playwright/mcp@latest --port 8931. HTTP sessions use a five-second heartbeat timeout. If the MCP client or proxy does not answer server-initiated pings, set the PLAYWRIGHT_MCP_PING_TIMEOUT_MS environment variable to a longer timeout in milliseconds, or set it to 0 to disable the heartbeat. Point the MCP client to the HTTP endpoint using the url configuration key: http://localhost:8931/mcp.

VS Code version requirement for agentic experience

VS Code v1.105 or later (released October 9, 2025) is needed for the agentic experience to function properly in VS Code.

Spec format includes application overview and test scenarios

A spec document includes an Application Overview describing key features and capabilities, followed by numbered Test Scenarios with descriptive names. Each scenario includes a Seed reference, numbered Steps with detailed actions, and Expected Results with specific validation points.

Three built-in Playwright Test Agents

Playwright comes with three agents out of the box: planner, generator, and healer. The planner explores the app and produces a Markdown test plan. The generator transforms the Markdown plan into Playwright Test files. The healer executes the test suite and automatically repairs failing tests. These agents can be used independently, sequentially, or as chained calls in an agentic loop.

Initialize Playwright Test Agents with init-agents command

Use the command 'npx playwright init-agents' to add Playwright Test Agent definitions to your project. The command accepts a --loop parameter to specify the AI tool: --loop=vscode, --loop=claude, --loop=codex, or --loop=opencode. These definitions should be regenerated whenever Playwright is updated to pick up new tools and instructions.

Planner agent input and output

The planner agent takes as input a clear request (e.g., 'Generate a plan for guest checkout'), a seed test that sets up the environment necessary to interact with your app, and optionally a Product Requirement Document (PRD) for context. It outputs a Markdown test plan that is human-readable but precise enough for test generation.

Planner uses seed test for initialization and as example

The planner will run the seed test to execute all initialization necessary for your test including global setup, project dependencies, and necessary fixtures and hooks. The planner also uses the seed test as an example of the style and structure for all generated tests.

Generator agent input and output

The generator agent takes a Markdown plan from the specs/ directory as input. It outputs a test suite under the tests/ directory. Generated tests may include initial errors that can be healed automatically by the healer agent. The generator verifies selectors and assertions live as it performs the scenarios.

Healer agent repairs failing tests

When a test fails, the healer agent replays the failing steps, inspects the current UI to locate equivalent elements or flows, suggests a patch (such as locator update or wait adjustment), and re-runs the test until it passes or until guardrails stop the loop. The output is either a passing test or a skipped test if the healer believes that functionality is broken.

Agent definitions directory structure

Agent definitions and generated files follow a structure: .github/ contains agent definitions, specs/ contains human-readable test plans (e.g., basic-operations.md), tests/ contains generated Playwright tests including a seed.spec.ts file for environment setup, and playwright.config.ts is at the root.

Agent definitions are instructions and MCP tools

Agent definitions are collections of instructions and MCP tools provided by Playwright. They should be regenerated whenever Playwright is updated.

Specs are structured human-readable test plans

Specs are structured plans describing scenarios in human-readable terms. They include steps, expected outcomes, and data. Specs can start from scratch or extend a seed test.

Seed tests provide page context for bootstrap execution

Seed tests provide a ready-to-use page context to bootstrap execution. They set up the environment necessary for agents to interact with your app.

Example seed.spec.ts file structure

A seed test is structured as: import { test, expect } from './fixtures'; followed by test('seed', async ({ page }) => { // test uses custom fixtures from ./fixtures });

Example generated test from spec

Example: specs/basic-operations.md generates tests/add-valid-todo.spec.ts. A generated test includes comments referencing the spec file and seed file (// spec: specs/basic-operations.md and // seed: tests/seed.spec.ts), imports fixtures, uses describe for test grouping, and includes numbered comments matching the spec steps with assertions validating expected results.

Give your agent this brain