playwright README

The project's README from github.com/microsoft/playwright. As one markdown file: README.md.

🎭 Playwright

npm version Chromium version Firefox version WebKit version Join Discord

Documentation | API reference

Playwright is a framework for web automation and testing. It drives Chromium, Firefox, and WebKit with a single API — in your tests, in your scripts, and as a tool for AI agents.

Get Started

Choose the path that fits your workflow:

Best for Install
Playwright Test End-to-end testing npm init playwright@latest
Playwright CLI Coding agents (Claude Code, Copilot) npm i -g @playwright/cli@latest
Playwright MCP AI agents and LLM-driven automation npx @playwright/mcp@latest
Playwright Library Browser automation scripts npm i playwright
VS Code Extension Test authoring and debugging in VS Code Install from Marketplace

Playwright Test

Playwright Test is a full-featured test runner built for end-to-end testing. It runs tests across Chromium, Firefox, and WebKit with full browser isolation, auto-waiting, and web-first assertions.

Install

npm init playwright@latest

Or add manually:

npm i -D @playwright/test
npx playwright install

Write a test

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 tests

npx playwright test

Tests run in parallel across all configured browsers, in headless mode by default. Each test gets a fresh browser context — full isolation with near-zero overhead.

Key capabilities

Auto-wait and web-first assertions. No artificial timeouts. Playwright waits for elements to be actionable, and assertions automatically retry until conditions are met.

Locators. Find elements with resilient locators that mirror how users see the page:

page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByPlaceholder('Search...')
page.getByTestId('login-form')

Test isolation. Each test runs in its own browser context — equivalent to a fresh browser profile. Save authentication state once and reuse it across tests:

// Save state after login
await page.context().storageState({ path: 'auth.json' });

// Reuse in other tests
test.use({ storageState: 'auth.json' });

Tracing. Capture execution traces, screenshots, and videos on failure. Inspect every action, DOM snapshot, network request, and console message in the Trace Viewer:

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

npx playwright show-trace trace.zip

Parallelism. Tests run in parallel by default across all configured browsers.

Full testing documentation

Playwright CLI

Playwright CLI is a command-line interface for browser automation designed for coding agents. It's more token-efficient than MCP — commands avoid loading large tool schemas and accessibility trees into the model context.

Install

npm install -g @playwright/cli@latest

Optionally install skills for richer agent integration:

playwright-cli install --skills

Usage

Point your coding agent at a task:

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

Or run commands directly:

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

Session monitoring

Use playwright-cli show to open a visual dashboard with live screencast previews of all running browser sessions. Click any session to zoom in and take remote control.

playwright-cli show

Full CLI documentation | GitHub

Playwright MCP

The Playwright MCP server gives AI agents full browser control through the Model Context Protocol. Agents interact with pages using structured accessibility snapshots — no vision models or screenshots required.

Setup

Add to your MCP client (VS Code, Cursor, Claude Desktop, Windsurf, etc.):

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

One-click install for VS Code:

Install in VS Code

For Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

How it works

Ask your AI assistant to interact with any web page:

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

The agent sees the page as a structured accessibility tree:

- heading "todos" [level=1]
- textbox "What needs to be done?" [ref=e5]
- listitem:
  - checkbox "Toggle Todo" [ref=e10]
  - text: "Buy groceries"

It uses element refs like e5 and e10 to click, type, and interact — deterministically and without visual ambiguity. Tools cover navigation, form filling, screenshots, network mocking, storage management, and more.

Full MCP documentation | GitHub

Playwright Library

Use playwright as a library for browser automation scripts — web scraping, PDF generation, screenshot capture, and any workflow that needs programmatic browser control without a test runner.

Install

npm i playwright

Examples

Take a screenshot:

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();

Generate a PDF:

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();

Emulate a mobile device:

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();

Intercept network 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();

Library documentation | API reference

VS Code Extension

The Playwright VS Code extension brings test running, debugging, and code generation directly into your editor.

Run and debug tests from the editor with a single click. Set breakpoints, inspect variables, and step through test execution with a live browser view.

Generate tests with CodeGen. Click "Record new" to open a browser — navigate and interact with your app while Playwright writes the test code for you.

Pick locators. Hover over any element in the browser to see the best available locator, then click to copy it to your clipboard.

Trace Viewer integration. Enable "Show Trace Viewer" in the sidebar to get a full execution trace after each test run — DOM snapshots, network requests, console logs, and screenshots at every step.

Install the extension | VS Code guide

Cross-Browser Support

Linux macOS Windows
Chromium1 154.0.8037.0 :white_check_mark: :white_check_mark: :white_check_mark:
WebKit 26.6 :white_check_mark: :white_check_mark: :white_check_mark:
Firefox 155.0 :white_check_mark: :white_check_mark: :white_check_mark:

Headless and headed execution on all platforms. 1 Uses Chrome for Testing by default.

Other Languages

Playwright is also available for Python, .NET, and Java.

Resources

playwright (microsoft/playwright)

framework
Searching Database…

97.9K ·GitHub
Playwright
What is this?Playwright is a framework for web testing and automation that drives Chromium, Firefox, and WebKit through a single API, usable in test suites, automation scripts, and as a tool for AI agents.
Is this one tool or several different ways to use it?It is actually five related pieces: Playwright Test (end-to-end test runner), Playwright CLI (for coding agents), Playwright MCP (AI agent browser control), Playwright Library (plain scripting), and a VS Code extension for authoring and debugging tests.
How do I start writing end-to-end tests with it?Scaffold a project with `npm init playwright@latest`, write a test, then run it — tests execute in parallel across all configured browsers in headless mode by default.
What do I need installed before trying it?Just Node.js 20 or newer; the browser binaries for Chromium, Firefox and WebKit get installed automatically through the npm install commands for each tool.
Does the MCP server rely on screenshots or vision models to see the page?No — agents interact through structured accessibility snapshots and element refs like e5 or e10, so clicking and typing work deterministically without any image-based reasoning.
Which browsers and operating systems does it actually support?Chromium, WebKit, and Firefox are all supported on Linux, macOS, and Windows, both headless and headed.
What does the Trace Viewer show after a test fails?It gives a full execution trace — every action, DOM snapshot, network request, console message, and screenshot captured during the run — so you can see exactly what happened before the failure.
Can I generate test code without writing it by hand?Yes, the VS Code extension has a CodeGen recorder: click 'Record new', interact with your app in the browser that opens, and Playwright writes the matching test code for you.
What can I use the Playwright Library for besides testing?It is a plain browser-automation library for scripts that need programmatic browser control without a test runner, such as web scraping, PDF generation, screenshot capture, mobile device emulation, and network request interception.
How do I monitor browser sessions that an agent is running via the CLI?Run `playwright-cli show` to open a visual dashboard with live screencast previews of every running session, and click any session to zoom in and take remote control.
What are similar projects?puppeteer, SeleniumBase, e2e, playwright-python, expect, assay, reticle, bb-browser
Which topics is it in?webkit, end-to-end-testing, test, e2e-testing, testing-tools, chromium, firefox, test-automation, screenshot, vscode-extension, chrome, playwright
Creator
microsoft
Size
239.6 MB
Stars
97.9K
Updated
CommitOct 16Releasev1.64.1Oct 14
Age
6y
Commits · 90 Days