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: rewrite README (#39982)
Pavel Feldman5fa11df998bf
diff --git a/README.md b/README.mdindex 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+```bashnpm 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+```bashnpm i -D @playwright/test-# install supported browsersnpx 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)