Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

docs: add getting started guides for MCP and CLI (#39835)

Pavel Feldman9abb493fffdc
diff --git a/docs/src/getting-started-cli.md b/docs/src/getting-started-cli.md
new file mode 100644
index 0000000000..c318a16512
--- /dev/null
+++ b/docs/src/getting-started-cli.md
@@ -0,0 +1,306 @@
+---
+id: getting-started-cli
+title: "Getting started - CLI for Agent"
+---
+
+## Introduction
+
+`playwright-cli` is a command-line interface for browser automation designed for coding agents. It provides token-efficient browser control through concise CLI commands and installable skills, making it ideal for agents that need to balance browser automation with large codebases and reasoning within limited context windows.
+
+### `playwright-cli` vs Playwright MCP
+
+- **`playwright-cli`** is best for **coding agents** (Claude Code, GitHub Copilot, etc.) that favor token-efficient, skill-based workflows. CLI commands avoid loading large tool schemas and verbose accessibility trees into the model context.
+- **MCP** is best for specialized agentic loops that benefit from persistent state and iterative reasoning over page structure, such as exploratory automation or long-running autonomous workflows. See the [MCP getting started guide](./getting-started-mcp.md).
+
+## Prerequisites
+
+Before you begin, make sure you have the following installed:
+- [Node.js](https://nodejs.org/) 18 or newer
+- A coding agent: Claude Code, GitHub Copilot, or similar
+
+## Installation
+
+Install `playwright-cli` globally:
+
+```bash
+npm install -g @playwright/cli@latest
+playwright-cli --help
+```
+
+Alternatively, install `@playwright/cli` as a local dependency and use `npx`:
+
+```bash
+npx playwright-cli --help
+```
+
+### Installing skills
+
+Coding agents like Claude Code and GitHub Copilot can use locally installed skills for richer context about available commands:
+
+```bash
+playwright-cli install --skills
+```
+
+### Skills-less operation
+
+You can also point your agent at the CLI directly and let it discover commands on its own:
+
+```txt
+Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
+Check playwright-cli --help for available commands.
+```
+
+## First Steps
+
+### Interactive demo
+
+Try asking your coding agent:
+
+```txt
+Use playwright skills to test https://demo.playwright.dev/todomvc/.
+Take screenshots for all successful and failing scenarios.
+```
+
+### Manual walkthrough
+
+You can also run commands manually to see how the CLI works:
+
+```bash
+playwright-cli open https://demo.playwright.dev/todomvc/ --headed
+playwright-cli type "Buy groceries"
+playwright-cli press Enter
+playwright-cli type "Water flowers"
+playwright-cli press Enter
+playwright-cli check e21
+playwright-cli screenshot
+```
+
+After each command, the CLI outputs a snapshot of the current page state:
+
+```txt
+### Page
+- Page URL: https://demo.playwright.dev/todomvc/#/
+- Page Title: React • TodoMVC
+### Snapshot
+[Snapshot](.playwright-cli/page-2026-02-14T19-22-42-679Z.yml)
+```
+
+## Core Commands
+
+### Interacting with pages
+
+```bash
+playwright-cli open [url] # open browser, optionally navigate to url
+playwright-cli goto <url> # navigate to a url
+playwright-cli click <ref> [button] # click an element
+playwright-cli type <text> # type text into editable element
+playwright-cli fill <ref> <text> # fill text into editable element
+playwright-cli select <ref> <value> # select an option in a dropdown
+playwright-cli check <ref> # check a checkbox or radio button
+playwright-cli uncheck <ref> # uncheck a checkbox
+playwright-cli hover <ref> # hover over element
+playwright-cli drag <startRef> <endRef> # drag and drop between elements
+playwright-cli upload <file> # upload files
+playwright-cli close # close the page
+```
+
+### Targeting elements
+
+Use element refs from snapshots to target elements:
+
+```bash
+playwright-cli snapshot # get snapshot with element refs
+playwright-cli click e15 # click using a ref
+```
+
+You can also use CSS or role selectors:
+
+```bash
+playwright-cli click "#main > button.submit"
+playwright-cli click "role=button[name=Submit]"
+playwright-cli click "#footer >> role=button[name=Submit]"
+```
+
+### Screenshots and snapshots
+
+```bash
+playwright-cli snapshot # capture page snapshot
+playwright-cli snapshot --filename=f # save snapshot to specific file
+playwright-cli screenshot # screenshot of the current page
+playwright-cli screenshot [ref] # screenshot of a specific element
+playwright-cli screenshot --filename=f # save with specific filename
+playwright-cli pdf # save page as PDF
+```
+
+### Navigation
+
+```bash
+playwright-cli go-back # go back
+playwright-cli go-forward # go forward
+playwright-cli reload # reload the page
+```
+
+### Keyboard and mouse
+
+```bash
+playwright-cli press <key> # press a key (e.g. Enter, ArrowLeft)
+playwright-cli keydown <key> # key down
+playwright-cli keyup <key> # key up
+playwright-cli mousemove <x> <y> # move mouse
+playwright-cli mousedown [button] # mouse button down
+playwright-cli mouseup [button] # mouse button up
+playwright-cli mousewheel <dx> <dy> # scroll
+```
+
+### Tabs
+
+```bash
+playwright-cli tab-list # list all tabs
+playwright-cli tab-new [url] # create a new tab
+playwright-cli tab-select <index> # select a tab
+playwright-cli tab-close [index] # close a tab
+```
+
+### Network
+
+```bash
+playwright-cli network # list network requests since page load
+playwright-cli route <pattern> [opts] # mock network requests
+playwright-cli route-list # list active routes
+playwright-cli unroute [pattern] # remove routes
+```
+
+### Storage
+
+```bash
+playwright-cli state-save [filename] # save storage state (cookies, localStorage)
+playwright-cli state-load <filename> # load storage state
+
+# Cookies
+playwright-cli cookie-list [--domain] # list cookies
+playwright-cli cookie-get <name> # get a cookie
+playwright-cli cookie-set <name> <val> # set a cookie
+playwright-cli cookie-delete <name> # delete a cookie
+playwright-cli cookie-clear # clear all cookies
+
+# localStorage
+playwright-cli localstorage-list # list entries
+playwright-cli localstorage-get <key> # get value
+playwright-cli localstorage-set <k> <v> # set value
+playwright-cli localstorage-delete <k> # delete entry
+playwright-cli localstorage-clear # clear all
+```
+
+### DevTools
+
+```bash
+playwright-cli console [min-level] # list console messages
+playwright-cli eval <func> [ref] # evaluate JavaScript on page
+playwright-cli run-code <code> # run Playwright code snippet
+playwright-cli tracing-start # start trace recording
+playwright-cli tracing-stop # stop trace recording
+playwright-cli video-start # start video recording
+playwright-cli video-stop [filename] # stop video recording
+```
+
+## Sessions
+
+The CLI keeps the browser profile in memory by default — cookies and storage state are preserved between calls within a session but lost when the browser closes. Use `--persistent` to save the profile to disk.
+
+### Named sessions
+
+Run multiple browser instances for different projects:
+
+```bash
+playwright-cli open https://playwright.dev
+playwright-cli -s=example open https://example.com --persistent
+playwright-cli list # list all sessions
+```
+
+You can configure your coding agent to use a specific session:
+
+```bash
+PLAYWRIGHT_CLI_SESSION=todo-app claude .
+```
+
+### Session management
+
+```bash
+playwright-cli list # list all sessions
+playwright-cli close-all # close all browsers
+playwright-cli kill-all # forcefully kill all browser processes
+playwright-cli -s=name delete-data # delete user data for a named session
+```
+
+## Monitoring
+
+Use `playwright-cli show` to open a visual dashboard for observing and controlling all running browser sessions:
+
+```bash
+playwright-cli show
+```
+
+The dashboard provides:
+
+- **Session grid** — all active sessions grouped by workspace, each with a live screencast preview, session name, current URL, and page title. Click any session to zoom in.
+- **Session detail** — a live view of the selected session with tab bar, navigation controls, and full remote control. Click into the viewport to take over mouse and keyboard; press Escape to release.
+
+## Configuration
+
+### Headed mode
+
+The CLI runs headless by default. To see the browser:
+
+```bash
+playwright-cli open https://playwright.dev --headed
+```
+
+### Browser selection
+
+```bash
+playwright-cli open --browser=chrome # use specific browser
+playwright-cli open --browser=firefox
+playwright-cli open --browser=webkit
+playwright-cli open --browser=msedge
+```
+
+### Configuration file
+
+For advanced settings, use a JSON config file:
+
+```bash
+playwright-cli --config path/to/config.json open example.com
+```
+
+The CLI also loads `.playwright/cli.config.json` automatically if present. The config file supports browser options, context options, network rules, timeouts, and more. Run `playwright-cli --help` for the full list of options.
+
+### Browser extension
+
+Connect to your existing browser tabs instead of launching a new browser:
+
+```bash
+playwright-cli open --extension
+```
+
+This requires the [Playwright MCP Bridge browser extension](https://github.com/user-attachments/packages/extension) to be installed.
+
+## Quick Reference
+
+| Action | Command |
+| ------------------------- | --------------------------------------------------- |
+| **Install CLI** | `npm install -g @playwright/cli@latest` |
+| **Install skills** | `playwright-cli install --skills` |
+| **Open a page** | `playwright-cli open https://example.com` |
+| **Click an element** | `playwright-cli click e15` |
+| **Type text** | `playwright-cli type "hello world"` |
+| **Take a screenshot** | `playwright-cli screenshot` |
+| **Get page snapshot** | `playwright-cli snapshot` |
+| **Run headed** | `playwright-cli open https://example.com --headed` |
+| **Use Firefox** | `playwright-cli open --browser=firefox` |
+| **Monitor sessions** | `playwright-cli show` |
+
+## What's Next
+
+- [Write tests using web-first assertions, page fixtures, and locators](./writing-tests.md)
+- [Run your tests on CI](./ci-intro.md)
+- [Learn more about the Trace Viewer](./trace-viewer.md)
\ No newline at end of file
diff --git a/docs/src/getting-started-mcp.md b/docs/src/getting-started-mcp.md
new file mode 100644
index 0000000000..65ff6d24d8
--- /dev/null
+++ b/docs/src/getting-started-mcp.md
@@ -0,0 +1,228 @@
+---
+id: getting-started-mcp
+title: "Getting started - MCP"
+---
+
+## Introduction
+
+The Playwright MCP server provides browser automation capabilities through the [Model Context Protocol](https://modelcontextprotocol.io), enabling LLMs to interact with web pages using structured accessibility snapshots. It works with VS Code, Cursor, Windsurf, Claude Desktop, and any other MCP client — no vision models required.
+
+## Prerequisites
+
+Before you begin, make sure you have the following installed:
+- [Node.js](https://nodejs.org/) 18 or newer
+- An MCP client: VS Code, Cursor, Windsurf, Claude Code, Claude Desktop, or similar
+
+## Getting Started
+
+### Installation
+
+Add the Playwright MCP server to your client using the standard configuration:
+
+```json
+{
+ "mcpServers": {
+ "playwright": {
+ "command": "npx",
+ "args": [
+ "@playwright/mcp@latest"
+ ]
+ }
+ }
+}
+```
+
+#### VS Code
+
+Click one of the buttons below to install directly:
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522playwright%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540playwright%252Fmcp%2540latest%2522%255D%257D)
+
+Or install via the VS Code CLI:
+
+```bash
+code --add-mcp '{"name":"playwright","command":"npx","args":["@playwright/mcp@latest"]}'
+```
+
+#### Cursor
+
+[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=Playwright&config=eyJjb21tYW5kIjoibnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QifQ%3D%3D)
+
+Or go to `Cursor Settings` → `MCP` → `Add new MCP Server` and use command type with `npx @playwright/mcp@latest`.
+
+#### Claude Code
+
+```bash
+claude mcp add playwright npx @playwright/mcp@latest
+```
+
+#### Claude Desktop
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user) and use the standard config above.
+
+#### Other clients
+
+The standard configuration works with most MCP clients, including Windsurf, Cline, Goose, Kiro, Codex, Copilot CLI, and others. Consult your client's MCP documentation for where to place the config.
+
+### First interaction
+
+Once the server is connected, ask your AI assistant to interact with a web page:
+
+```txt
+Navigate to https://demo.playwright.dev/todomvc and add a few todo items.
+```
+
+The assistant will use Playwright MCP tools to open the browser, navigate to the page, and interact with elements — all through structured accessibility snapshots rather than screenshots.
+
+## Core Features
+
+### Accessibility snapshots
+
+Playwright MCP operates on the page's accessibility tree, not pixels. When a tool runs, it returns a structured snapshot showing the page elements, their roles, and text content. The LLM uses element references from these snapshots to interact with the page:
+
+```txt
+- heading "todos" [level=1]
+- textbox "What needs to be done?" [ref=e5]
+- listitem:
+ - checkbox "Toggle Todo" [ref=e10]
+ - text: "Buy groceries"
+```
+
+The LLM reads this snapshot and uses `ref=e5` to type into the textbox or `ref=e10` to check the checkbox.
+
+### Interacting with pages
+
+Playwright MCP provides tools for all common browser interactions:
+
+- **Navigation**: Open URLs, go back/forward, reload pages.
+- **Clicking and typing**: Click elements, type text, fill forms, select dropdowns.
+- **Screenshots**: Capture the current page or specific elements for visual verification.
+- **Keyboard and mouse**: Press keys, hover, drag and drop.
+- **Dialogs**: Accept or dismiss browser dialogs.
+- **Tabs**: Create, close, and switch between browser tabs.
+
+### Running Playwright code
+
+For complex interactions that go beyond individual tool calls, use the `browser_run_code` tool to execute Playwright scripts directly:
+
+```txt
+Run this Playwright code to verify the todo count:
+async (page) => {
+ const count = await page.getByTestId('todo-count').textContent();
+ return count;
+}
+```
+
+### Network monitoring and mocking
+
+Inspect network traffic and mock API responses:
+
+- **View network requests**: List all requests made since page load.
+- **Mock routes**: Set up URL pattern matching to return custom responses.
+- **Console messages**: Access browser console output for debugging.
+
+### Storage state
+
+Save and restore browser state including cookies and localStorage:
+
+- **Save state**: Persist authentication and session data to a file.
+- **Restore state**: Load previously saved state into a new session.
+- **Cookie management**: List, get, set, and delete individual cookies.
+
+## Configuration
+
+### Headed mode
+
+By default, Playwright MCP runs the browser in headed mode so you can see what's happening. To run headless:
+
+```json
+{
+ "mcpServers": {
+ "playwright": {
+ "command": "npx",
+ "args": [
+ "@playwright/mcp@latest",
+ "--headless"
+ ]
+ }
+ }
+}
+```
+
+### Browser selection
+
+Choose which browser to use:
+
+```json
+{
+ "mcpServers": {
+ "playwright": {
+ "command": "npx",
+ "args": [
+ "@playwright/mcp@latest",
+ "--browser=firefox"
+ ]
+ }
+ }
+}
+```
+
+Supported values: `chrome`, `firefox`, `webkit`, `msedge`.
+
+### User profile
+
+Playwright MCP supports three profile modes:
+
+- **Persistent (default)**: Login state and cookies are preserved between sessions. The profile is stored in `ms-playwright/mcp-{channel}-profile` in your platform's cache directory. Override with `--user-data-dir`.
+- **Isolated**: Each session starts fresh. Pass `--isolated` to enable. You can load initial state with `--storage-state`.
+- **Browser extension**: Connect to your existing browser tabs with the [Playwright MCP Bridge extension](https://github.com/user-attachments/packages/extension). Pass `--extension` to enable.
+
+### Configuration file
+
+For advanced configuration, use a JSON config file:
+
+```bash
+npx @playwright/mcp@latest --config path/to/config.json
+```
+
+The config file supports browser options, context options, network rules, timeouts, and more. See the [Playwright MCP repository](https://github.com/microsoft/playwright-mcp/blob/main/packages/playwright-mcp/config.d.ts) for the full schema.
+
+### Standalone server
+
+When running a headed browser on a system without a display or from IDE worker processes, start the MCP server separately with HTTP transport:
+
+```bash
+npx @playwright/mcp@latest --port 8931
+```
+
+Then point your MCP client to the HTTP endpoint:
+
+```json
+{
+ "mcpServers": {
+ "playwright": {
+ "url": "http://localhost:8931/mcp"
+ }
+ }
+}
+```
+
+## Quick Reference
+
+| Action | How to do it |
+| ------------------------- | ------------------------------------------------------------- |
+| **Install server** | Add standard config to your MCP client |
+| **Navigate to a page** | Ask: "Go to https://example.com" |
+| **Click an element** | Ask: "Click the Submit button" |
+| **Fill a form** | Ask: "Fill in the email field with [email protected]" |
+| **Take a screenshot** | Ask: "Take a screenshot of the page" |
+| **Run Playwright code** | Ask: "Run this Playwright code: ..." |
+| **Mock an API** | Ask: "Mock the /api/users endpoint to return ..." |
+| **Use headed mode** | Default. Pass `--headless` to disable |
+| **Choose a browser** | Pass `--browser=firefox` in args |
+
+## What's Next
+
+- [Write tests using web-first assertions, page fixtures, and locators](./writing-tests.md)
+- [Run your tests on CI](./ci-intro.md)
+- [Learn more about the Trace Viewer](./trace-viewer.md)
\ No newline at end of file