Skip to content

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

docs: rewrite README (#39982)

Pavel Feldman5fa11df998bf
diff --git a/README.md b/README.md
index 4a44d1f0cd..1641f31a7d 100644
--- a/README.md
+++ b/README.md
@@ -4,167 +4,315 @@
## [Documentation](https://playwright.dev) | [API reference](https://playwright.dev/docs/api/class-playwright)
-Playwright is a framework for Web Testing and Automation. It allows testing [Chromium](https://www.chromium.org/Home)<sup>1</sup>, [Firefox](https://www.mozilla.org/en-US/firefox/new/) and [WebKit](https://webkit.org/) with a single API. Playwright is built to enable cross-browser web automation that is **ever-green**, **capable**, **reliable**, and **fast**.
+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.
-| | Linux | macOS | Windows |
-| :--- | :---: | :---: | :---: |
-| Chromium<sup>1</sup> <!-- GEN:chromium-version -->147.0.7727.15<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| WebKit <!-- GEN:webkit-version -->26.4<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-| Firefox <!-- GEN:firefox-version -->148.0.2<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-
-Headless execution is supported for all browsers on all platforms. Check out [system requirements](https://playwright.dev/docs/intro#system-requirements) for details.
+## Get Started
-Looking for Playwright for [Python](https://playwright.dev/python/docs/intro), [.NET](https://playwright.dev/dotnet/docs/intro), or [Java](https://playwright.dev/java/docs/intro)?
+Choose the path that fits your workflow:
-<sup>1</sup> Playwright uses [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) by default.
+| | Best for | Install |
+|---|---|---|
+| **[Playwright Test](#playwright-test)** | End-to-end testing | `npm init playwright@latest` |
+| **[Playwright CLI](#playwright-cli)** | Coding agents (Claude Code, Copilot) | `npm i -g @playwright/cli@latest` |
+| **[Playwright MCP](#playwright-mcp)** | AI agents and LLM-driven automation | `npx @playwright/mcp@latest` |
+| **[Playwright Library](#playwright-library)** | Browser automation scripts | `npm i playwright` |
+| **[VS Code Extension](#vs-code-extension)** | Test authoring and debugging in VS Code | [Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) |
-## Installation
+---
-Playwright has its own test runner for end-to-end tests, we call it Playwright Test.
+## Playwright Test
-### Using init command
+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.
-The easiest way to get started with Playwright Test is to run the init command.
+### Install
-```Shell
-# Run from your project's root directory
+```bash
npm init playwright@latest
-# Or create a new project
-npm init playwright@latest new-project
```
-This will create a configuration file, optionally add examples, a GitHub Action workflow and a first test example.spec.ts. You can now jump directly to writing assertions section.
-
-### Manually
+Or add manually:
-Add dependency and install browsers.
-
-```Shell
+```bash
npm i -D @playwright/test
-# install supported browsers
npx playwright install
```
-You can optionally install only selected browsers, see [install browsers](https://playwright.dev/docs/cli#install-browsers) for more details. Or you can install no browsers at all and use existing [browser channels](https://playwright.dev/docs/browsers).
+### Write a test
-* [Getting started](https://playwright.dev/docs/intro)
-* [API reference](https://playwright.dev/docs/api/class-playwright)
+```TypeScript
+import { test, expect } from '@playwright/test';
-## Capabilities
+test('has title', async ({ page }) => {
+ await page.goto('https://playwright.dev/');
+ await expect(page).toHaveTitle(/Playwright/);
+});
-### Resilient • No flaky tests
+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();
+});
+```
-**Auto-wait**. Playwright waits for elements to be actionable prior to performing actions. It also has a rich set of introspection events. The combination of the two eliminates the need for artificial timeouts - a primary cause of flaky tests.
+### Run tests
-**Web-first assertions**. Playwright assertions are created specifically for the dynamic web. Checks are automatically retried until the necessary conditions are met.
+```bash
+npx playwright test
+```
-**Tracing**. Configure test retry strategy, capture execution trace, videos and screenshots to eliminate flakes.
+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.
-### No trade-offs • No limits
+### Key capabilities
-Browsers run web content belonging to different origins in different processes. Playwright is aligned with the architecture of the modern browsers and runs tests out-of-process. This makes Playwright free of the typical in-process test runner limitations.
+**Auto-wait and web-first assertions.** No artificial timeouts. Playwright waits for elements to be actionable, and assertions automatically retry until conditions are met.
-**Multiple everything**. Test scenarios that span multiple tabs, multiple origins and multiple users. Create scenarios with different contexts for different users and run them against your server, all in one test.
+**Locators.** Find elements with resilient locators that mirror how users see the page:
-**Trusted events**. Hover elements, interact with dynamic controls and produce trusted events. Playwright uses real browser input pipeline indistinguishable from the real user.
+```TypeScript
+page.getByRole('button', { name: 'Submit' })
+page.getByLabel('Email')
+page.getByPlaceholder('Search...')
+page.getByTestId('login-form')
+```
-Test frames, pierce Shadow DOM. Playwright selectors pierce shadow DOM and allow entering frames seamlessly.
+**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:
-### Full isolation • Fast execution
+```TypeScript
+// Save state after login
+await page.context().storageState({ path: 'auth.json' });
-**Browser contexts**. Playwright creates a browser context for each test. Browser context is equivalent to a brand new browser profile. This delivers full test isolation with zero overhead. Creating a new browser context only takes a handful of milliseconds.
+// Reuse in other tests
+test.use({ storageState: 'auth.json' });
+```
-**Log in once**. Save the authentication state of the context and reuse it in all the tests. This bypasses repetitive log-in operations in each test, yet delivers full isolation of independent tests.
+**Tracing.** Capture execution traces, screenshots, and videos on failure. Inspect every action, DOM snapshot, network request, and console message in the [Trace Viewer](https://playwright.dev/docs/trace-viewer):
-### Powerful Tooling
+```TypeScript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ trace: 'on-first-retry',
+ },
+});
+```
-**[Codegen](https://playwright.dev/docs/codegen)**. Generate tests by recording your actions. Save them into any language.
+```bash
+npx playwright show-trace trace.zip
+```
-**[Playwright inspector](https://playwright.dev/docs/inspector)**. Inspect page, generate selectors, step through the test execution, see click points and explore execution logs.
+<!-- TODO: screenshot of trace viewer -->
-**[Trace Viewer](https://playwright.dev/docs/trace-viewer)**. Capture all the information to investigate the test failure. Playwright trace contains test execution screencast, live DOM snapshots, action explorer, test source and many more.
+**Parallelism.** Tests run in parallel by default across all configured browsers.
-Looking for Playwright for [TypeScript](https://playwright.dev/docs/intro), [JavaScript](https://playwright.dev/docs/intro), [Python](https://playwright.dev/python/docs/intro), [.NET](https://playwright.dev/dotnet/docs/intro), or [Java](https://playwright.dev/java/docs/intro)?
+[Full testing documentation](https://playwright.dev/docs/intro)
-## Examples
+---
-To learn how to run these Playwright Test examples, check out our [getting started docs](https://playwright.dev/docs/intro).
+## Playwright CLI
-#### Page screenshot
+[Playwright CLI](https://github.com/microsoft/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.
-This code snippet navigates to Playwright homepage and saves a screenshot.
+### Install
-```TypeScript
-import { test } from '@playwright/test';
+```bash
+npm install -g @playwright/cli@latest
+```
-test('Page Screenshot', async ({ page }) => {
- await page.goto('https://playwright.dev/');
- await page.screenshot({ path: `example.png` });
-});
+Optionally install skills for richer agent integration:
+
+```bash
+playwright-cli install --skills
```
-#### Mobile and geolocation
+### Usage
-This snippet emulates Mobile Safari on a device at given geolocation, navigates to maps.google.com, performs the action and takes a screenshot.
+Point your coding agent at a task:
-```TypeScript
-import { test, devices } from '@playwright/test';
-
-test.use({
- ...devices['iPhone 13 Pro'],
- locale: 'en-US',
- geolocation: { longitude: 12.492507, latitude: 41.889938 },
- permissions: ['geolocation'],
-})
-
-test('Mobile and geolocation', async ({ page }) => {
- await page.goto('https://maps.google.com');
- await page.getByText('Your location').click();
- await page.waitForRequest(/.*preview\/pwa/);
- await page.screenshot({ path: 'colosseum-iphone.png' });
-});
+```
+Test the "add todo" flow on https://demo.playwright.dev/todomvc using playwright-cli.
+Take screenshots for all successful and failing scenarios.
```
-#### Evaluate in browser context
+Or run commands directly:
-This code snippet navigates to example.com, and executes a script in the page context.
+```bash
+playwright-cli open https://demo.playwright.dev/todomvc/ --headed
+playwright-cli type "Buy groceries"
+playwright-cli press Enter
+playwright-cli screenshot
+```
-```TypeScript
-import { test } from '@playwright/test';
-
-test('Evaluate in browser context', async ({ page }) => {
- await page.goto('https://www.example.com/');
- const dimensions = await page.evaluate(() => {
- return {
- width: document.documentElement.clientWidth,
- height: document.documentElement.clientHeight,
- deviceScaleFactor: window.devicePixelRatio
+### 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.
+
+```bash
+playwright-cli show
+```
+
+<!-- TODO: screenshot of playwright-cli show dashboard -->
+
+[Full CLI documentation](https://playwright.dev/docs/cli-agent) | [GitHub](https://github.com/microsoft/playwright-cli)
+
+---
+
+## Playwright MCP
+
+The [Playwright MCP server](https://github.com/microsoft/playwright-mcp) gives AI agents full browser control through the [Model Context Protocol](https://modelcontextprotocol.io). 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.):
+
+```json
+{
+ "mcpServers": {
+ "playwright": {
+ "command": "npx",
+ "args": ["@playwright/mcp@latest"]
}
- });
- console.log(dimensions);
-});
+ }
+}
+```
+
+**One-click install for VS Code:**
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20MCP%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)
+
+**For Claude Code:**
+
+```bash
+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"
```
-#### Intercept network requests
+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](https://playwright.dev/docs/mcp) | [GitHub](https://github.com/microsoft/playwright-mcp)
+
+---
+
+## 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
+
+```bash
+npm i playwright
+```
-This code snippet sets up request routing for a page to log all network requests.
+### Examples
+
+**Take a screenshot:**
```TypeScript
-import { test } from '@playwright/test';
-
-test('Intercept network requests', async ({ page }) => {
- // Log and continue all network requests
- await page.route('**', route => {
- console.log(route.request().url());
- route.continue();
- });
- await page.goto('http://todomvc.com');
-});
+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:**
+
+```TypeScript
+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:**
+
+```TypeScript
+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:**
+
+```TypeScript
+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](https://playwright.dev/docs/library) | [API reference](https://playwright.dev/docs/api/class-playwright)
+
+---
+
+## VS Code Extension
+
+The [Playwright VS Code extension](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) brings test running, debugging, and code generation directly into your editor.
+
+<!-- TODO: hero screenshot of VS Code with Playwright sidebar -->
+
+**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](https://marketplace.visualstudio.com/items?itemName=ms-playwright.playwright) | [VS Code guide](https://playwright.dev/docs/getting-started-vscode)
+
+---
+
+## Cross-Browser Support
+
+| | Linux | macOS | Windows |
+| :--- | :---: | :---: | :---: |
+| Chromium<sup>1</sup> <!-- GEN:chromium-version -->147.0.7727.15<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| WebKit <!-- GEN:webkit-version -->26.4<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+| Firefox <!-- GEN:firefox-version -->148.0.2<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
+
+Headless and headed execution on all platforms. <sup>1</sup> Uses [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing) by default.
+
+## Other Languages
+
+Playwright is also available for [Python](https://playwright.dev/python/docs/intro), [.NET](https://playwright.dev/dotnet/docs/intro), and [Java](https://playwright.dev/java/docs/intro).
+
## Resources
* [Documentation](https://playwright.dev)
-* [API reference](https://playwright.dev/docs/api/class-playwright/)
+* [API reference](https://playwright.dev/docs/api/class-playwright)
+* [MCP server](https://github.com/microsoft/playwright-mcp)
+* [CLI for coding agents](https://github.com/microsoft/playwright-cli)
+* [VS Code extension](https://github.com/microsoft/playwright-vscode)
* [Contribution guide](CONTRIBUTING.md)
* [Changelog](https://github.com/microsoft/playwright/releases)
+* [Discord](https://aka.ms/playwright/discord)