Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.
TypeScript automationchromechromiume2e-testingelectronend-to-end-testingfirefoxjavascriptplaywrighttesttest-automationtestingtesting-toolswebwebkit
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.mdnew file mode 100644index 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 filediff --git a/docs/src/getting-started-mcp.md b/docs/src/getting-started-mcp.mdnew file mode 100644index 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