microsoft/playwright instruction manual

1. What Playwright is, and how it relates to Claude Code

Playwright is Microsoft’s Apache-2.0 framework for web testing and browser automation. Its single API drives Chromium, Firefox, and WebKit in tests, scripts, and agent-controlled workflows. The supplied documentation presents five user-facing surfaces: Playwright Test for end-to-end tests; Playwright CLI for coding agents; Playwright MCP for model-driven browser control; the Playwright Library for custom scripts; and a VS Code extension for authoring and debugging.

**Claude Code classification:** **tool surface via MCP, plus an external CLI used alongside Claude Code**. This is not documented as a native Claude Code plugin, hook, or context-injection package. The strongest direct integration is the documented Claude Code MCP registration, which exposes browser tools through Model Context Protocol. The separately installed Playwright CLI is explicitly designed for coding agents including Claude Code, and optional skills enrich that CLI integration. The Chrome extension can connect MCP clients to already-open browser tabs and an existing signed-in profile.

Choose one surface according to the job:

• Use **Playwright Test** for repeatable end-to-end test suites with isolation, retries, traces, and assertions.
• Use **Playwright CLI** when a coding agent should issue compact browser commands without loading MCP tool schemas and accessibility trees into its context.
• Use **Playwright MCP** when an AI client needs structured, model-visible browser tools.
• Use the **Library** for standalone Node automation such as screenshots or PDFs.
• Use the **VS Code extension** for editor-based running, debugging, recording, and locator selection.

The repository also contains maintainer-oriented Bidi tests, test assets, a synchronous WebP codec, injected page helpers, and Windows dependency tooling; those are covered separately below.

2. Playwright Test: install, write, locate, isolate, trace, and run

For a new end-to-end testing setup, use the documented initializer:

npm init playwright@latest

To add the runner manually, install the package and its browsers:

npm i -D @playwright/test
npx playwright install

A test receives an isolated `page`. `page.goto()` navigates; `expect(...).toHaveTitle()` retries until the title matches; role-based locators model user-visible semantics; `click()` waits until the target is actionable; and `toBeVisible()` is a retrying web-first assertion.

import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await expect(page).toHaveTitle(/Playwright/);
});

test('get started link', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
});

Run configured tests with:

npx playwright test

Tests are headless and parallel by default across configured browsers. Every test receives a fresh browser context, comparable to a clean browser profile. Resilient locator forms include `page.getByRole('button', { name: 'Submit' })`, `page.getByLabel('Email')`, `page.getByPlaceholder('Search...')`, and `page.getByTestId('login-form')`.

To preserve a login, `page.context().storageState({ path: 'auth.json' })` writes browser state. Apply it elsewhere with `test.use({ storageState: 'auth.json' })`.

Tracing can retain actions, DOM snapshots, requests, console messages, screenshots, and videos around failures. In `playwright.config.ts`, set `use: { trace: 'on-first-retry' }` inside `defineConfig(...)`. Open a resulting archive with:

npx playwright show-trace trace.zip

3. Playwright CLI for Claude Code and other coding agents

The separately documented Playwright CLI is optimized for coding agents and described as more token-efficient than MCP because commands do not inject large tool schemas or accessibility trees into model context. Install it globally exactly as documented:

npm install -g @playwright/cli@latest

Optional agent skills provide richer integration:

playwright-cli install --skills

The supplied files do not identify the installed skill files, their exact Claude Code location, or their individual behavior, so no stronger native-extension claim is warranted.

A documented natural-language task for an agent is:

Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
Take screenshots for all successful and failing scenarios.

Direct commands can perform the same kind of interaction:

playwright-cli open https://demo.playwright.dev/todomvc/ --headed
playwright-cli type "Buy groceries"
playwright-cli press Enter
playwright-cli screenshot

Here, `open` starts and navigates a visible browser because `--headed` is present; `type` enters the supplied text; `press Enter` sends the Enter key; and `screenshot` captures the current page. The README does not document output naming or additional flags, so rely on the linked CLI documentation for behavior beyond these examples.

To monitor active sessions, open the visual dashboard:

playwright-cli show

The dashboard provides live screencast previews of all running browser sessions. Selecting a session zooms into it and permits remote control. This CLI path is the most explicit fit when Claude Code is operating through shell commands, while MCP is the fit when browser actions should appear as protocol tools.

4. Playwright MCP and structured browser control

Playwright MCP gives an AI client browser control through Model Context Protocol. Register it in a generic MCP client configuration with:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

For Claude Code, the repository documents this direct command:

claude mcp add playwright npx @playwright/mcp@latest

After registration, a supported request is:

Navigate to https://demo.playwright.dev/todomvc and add a few todo items.

Rather than requiring visual interpretation, the agent receives a structured accessibility snapshot such as a heading, textbox, list item, checkbox, and text, each actionable element carrying a reference such as `e5` or `e10`. The agent uses those references to type, click, and otherwise interact deterministically. The documented tool scope includes navigation, form filling, screenshots, network mocking, and storage management. Exact tool names and argument schemas are not present in the supplied repository files, so this manual does not invent them.

A one-click VS Code MCP installation link is provided in the README, while the JSON configuration is also stated to suit clients such as VS Code, Cursor, Claude Desktop, and Windsurf. Note the distinction: Claude Desktop is named among generic MCP clients, but the explicit `claude mcp add` command is the evidence for Claude Code.

MCP is best when the assistant should receive a formal browser tool surface. Prefer the CLI when minimizing model-context overhead is more important. In either mode, browser actions can affect real websites; select targets and authenticated state deliberately.

5. Connecting MCP to an existing Chrome profile with the Playwright extension

The Playwright Chrome Extension lets an MCP-connected assistant use pages in an existing Chrome, Edge, or Chromium profile, including its cookies, sessions, and signed-in state. Install the linked **Playwright Extension** from the Chrome Web Store, then start MCP with `--extension`:

{
  "mcpServers": {
    "playwright-extension": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--extension"
      ]
    }
  }
}

On first interaction, a selection page lets you choose the tab the model can reach. Multiple clients may connect simultaneously. Each receives a separately named and colored tab group and sees only tabs in that group; one tab can belong to only one client. Dragging tabs into or out of a group changes access. The status page lists connections and allows individual disconnection.

Connections require approval by default. To allow automatic connection, copy the profile-specific `PLAYWRIGHT_MCP_EXTENSION_TOKEN` shown by the extension and add it as documented:

{
  "mcpServers": {
    "playwright-extension": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--extension"],
      "env": {
        "PLAYWRIGHT_MCP_EXTENSION_TOKEN": "your-token-here"
      }
    }
  }
}

If several profiles contain the extension, it otherwise connects to the most recently used one. Find the final component of **Profile Path** at `chrome://version` and select it with `--profile-dir-name`:

{
  "mcpServers": {
    "playwright-extension": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--extension", "--profile-dir-name", "Profile 2"]
    }
  }
}

`PLAYWRIGHT_MCP_PROFILE_DIR_NAME` is the documented environment-variable alternative. Tokens are profile-specific. Because this mode grants access to existing authenticated state, tab grouping, approvals, and token secrecy are important control boundaries.

6. Playwright Library: screenshots, PDFs, devices, and request interception

Install the Node library without the test runner using:

npm i playwright

For a screenshot, import `chromium`, launch it, create a page, navigate, write the image, and close the browser:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'screenshot.png' });
await browser.close();

PDF generation follows the same lifecycle. `page.pdf()` writes an A4 document:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://playwright.dev/');
await page.pdf({ path: 'page.pdf', format: 'A4' });
await browser.close();

Device emulation uses a predefined descriptor when creating the browser context. This example applies the `iPhone 15` profile before opening the page:

import { chromium, devices } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext(devices['iPhone 15']);
const page = await context.newPage();
await page.goto('https://playwright.dev/');
await page.screenshot({ path: 'mobile.png' });
await browser.close();

Network routing can intercept matching requests. Here, `page.route()` matches PNG and JPEG URLs and `route.abort()` prevents those requests:

import { chromium } from 'playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.route('**/*.{png,jpg,jpeg}', route => route.abort());
await page.goto('https://playwright.dev/');
await browser.close();

The README identifies web scraping as another library use, but supplies no scraping example. It also links the full API reference for functionality not documented in the provided files.

7. VS Code, browser/platform coverage, and language choices

The Playwright VS Code extension is installed from the linked Visual Studio Marketplace listing. It adds four documented workflows to the editor. First, tests can be run or debugged with a click; debugging supports breakpoints, variable inspection, stepwise execution, and a live browser view. Second, **Record new** opens a browser and CodeGen writes test code while you navigate and interact. Third, locator picking highlights an element, proposes the best available locator, and copies it when selected. Fourth, enabling **Show Trace Viewer** in the sidebar displays a trace after each run, including DOM snapshots, network requests, console logs, and screenshots at each step.

Do not confuse this editor extension with the Chrome extension. The VS Code extension authors and debugs tests; the Chrome extension exposes selected tabs and an existing profile to Playwright MCP.

The documented browser matrix covers Chromium, WebKit, and Firefox on Linux, macOS, and Windows, with both headless and headed execution. The supplied README identifies Chromium 154.0.8037.0, WebKit 26.6, and Firefox 155, and says Chromium uses Chrome for Testing by default. Treat those versions as the state recorded in the supplied file rather than a permanent compatibility promise.

The main examples use TypeScript/JavaScript packages, and repository metadata identifies TypeScript as the primary language. First-party Playwright variants are also linked for Python, .NET, and Java, but no installation commands or API examples for those languages were supplied, so they are not reproduced here.

Useful first-party destinations named by the repository include the Playwright documentation, API reference, MCP repository, coding-agent CLI repository, VS Code extension repository, contribution guide, GitHub releases, and Playwright Discord. For undocumented options, consult those linked first-party references rather than guessing commands.

8. Repository-maintainer utilities, internal APIs, and evidence limits

For Bidi development, the repository documents cloning, building, installing Chromium, and running Mozilla Firefox projects:

git clone https://github.com/microsoft/playwright.git
cd playwright
npm run build
npx playwright install chromium
npm run biditest -- --project='moz-firefox-*'

`npm run watch` is the documented watch-mode alternative to the build. Firefox beta can be installed with `npx -y @puppeteer/browsers install firefox@beta`; set `BIDI_FFPATH` to its executable before `npm run biditest -- --project='moz-firefox-*'`. `BIDI_CRPATH` similarly selects a custom Chromium executable.

The internal Node-only WebP module exports synchronous `encodeWebp(image, { quality })`, `encodeWebp(image, { lossless: true })`, and `decodeWebp(buffer)`. Quality is 0–100; for lossy output it is image quality, and for lossless output it is compression effort. Decoding returns RGBA `data`, `width`, and `height`. The WASM loads lazily on first call. Maintainers can rebuild the pinned libwebp/Emscripten artifacts from `utils/libwebp-wasm/` with `./build.sh`; `SIMD=0 ./build.sh` makes the smaller, slower scalar build. `EMSDK_DIR` can reuse an existing emsdk. Browser-main-thread synchronous use is not supported in practice.

Other documented internals are narrower: `packages/playwright-core` is the no-browser package; injected helper sources are bundled at build time into generated source constants; the Windows `PrintDeps` tool resolves DLL dependencies and is built by opening `PrintDeps.sln` in Visual Studio 2019 and choosing `x64/Release`. The test font is regenerated after `pip3 install fonttools brotli` with `python3 tests/assets/webfont/generate_font.py`. Modernizr expectations require a remote HTTPS host and manual checks in Safari Technology Preview and Apple iPhone; no copy-paste server command is supplied.

Vendored WPT, axe-core, and proxy files document provenance and local modifications, not public runtime APIs. This manual is limited to the supplied first-party files; it does not claim undocumented commands, MCP schemas, CLI flags, telemetry behavior, or security guarantees.