Playwright: Cross-Browser Web Testing and Automation

What Playwright is

Playwright is Microsoft's open-source framework for web automation and testing. Its README sums it up in one line: it drives Chromium, Firefox and WebKit with a single API, in your tests, in your scripts, and as a tool for AI agents. The same engine powers several products in one repository: Playwright Test, an end-to-end test runner; the Playwright library for general browser automation; a VS Code extension for authoring and debugging tests; and, more recently, a CLI and an MCP server designed for coding agents and LLM-driven automation.

The problem it targets is the long-standing pain of browser testing: flaky tests caused by timing, separate tooling per browser, and slow, hard-to-debug failures in CI. Playwright's answer is auto-waiting, retrying web-first assertions, isolated browser contexts per test, and detailed traces of every run. It is licensed under Apache-2.0, written in TypeScript, and available for JavaScript/TypeScript, Python, .NET and Java.

The audience is wide. Front-end and full-stack developers use Playwright Test to cover user flows across browsers; QA engineers use codegen and the trace viewer to build and debug suites; backend and data teams use the library for screenshots, PDFs and scripted browsing; and teams building AI agents use the MCP server or CLI to give a model controlled access to a real browser.

How it works

One API, three browser engines

Playwright downloads its own builds of Chromium, Firefox and WebKit, and each version of Playwright needs specific versions of those browser binaries. The README's cross-browser table shows all three supported on Linux, macOS and Windows, in headless and headed modes, with Chromium using Chrome for Testing by default. The browsers guide explains the details: Playwright's Firefox tracks the recent Firefox Stable build and its WebKit is derived from the latest WebKit main branch sources, often before those changes reach Safari. Both rely on patches, so Playwright does not work with branded Firefox or Safari. For Chromium-family browsers you can also target branded Google Chrome and Microsoft Edge through channels.

For headless runs, Playwright ships a separate Chromium headless shell alongside the regular Chromium build. If you only run headless tests, for example in CI, the docs say you can skip downloading full Chromium with the --only-shell install flag.

Browser contexts and isolation

Each test in Playwright Test gets a fresh browser context, which the README describes as equivalent to a fresh browser profile, with full isolation and near-zero overhead. Because contexts are cheap, tests can run in parallel by default across all configured browsers without sharing cookies or storage. Authentication state can be saved once with storageState and reused across tests, so suites don't need to log in through the UI for every case.

Auto-waiting, locators and assertions

Actions wait for elements to be actionable before acting, and web-first assertions such as toBeVisible() and toHaveTitle() retry until their condition is met, so tests don't need artificial timeouts. Locators are designed to mirror how users perceive a page: by role, label, placeholder or test ID, for example page.getByRole('button', { name: 'Submit' }) or page.getByLabel('Email').

Accessibility snapshots for agents

The MCP server and CLI expose the browser to AI agents through structured accessibility snapshots rather than screenshots. The README shows the agent seeing a tree of headings, textboxes and list items, each with element refs such as e5 that the agent uses to click and type. The project says this lets agents act deterministically without vision models. The CLI is pitched as more token-efficient than MCP, because its commands avoid loading large tool schemas and accessibility trees into the model's context.

Key features

• Cross-browser testing. Chromium, Firefox and WebKit from one API, plus branded Chrome and Edge channels and emulated mobile and tablet devices from a built-in device registry.
• Playwright Test runner. Parallel execution by default, projects per browser, fixtures, retries, sharding, HTML reporting and screenshot assertions; the languages page calls out its parallelization, screenshot assertions, HTML reporter and automatic tracing.
• Auto-wait and web-first assertions. Actions wait for actionability and assertions retry automatically, removing most explicit waits.
• Resilient locators. Role, label, placeholder and test-ID locators that match how users see the page.
• Trace Viewer. Traces capture every action, DOM snapshot, network request and console message; trace: 'on-first-retry' records a trace on the first retry of a failed test.
• Codegen. npx playwright codegen opens a browser and the Playwright Inspector and writes test code as you interact with your app.
• Test agents. Three built-in agents: a planner that explores the app and writes a Markdown test plan, a generator that turns the plan into test files, and a healer that runs the suite and repairs failing tests.
• Playwright MCP server. Gives MCP clients such as VS Code, Cursor, Claude Desktop and Windsurf browser control, with tools for navigation, form filling, screenshots, network mocking and storage management.
• Playwright CLI. A command-line interface for coding agents, with a playwright-cli show dashboard that streams live previews of running browser sessions and lets you take remote control.
• Library mode. Screenshots, PDF generation, device emulation and network interception from plain scripts without the test runner.
• VS Code extension. Run and debug tests with breakpoints, record new tests, pick locators by hovering, and open traces after each run.

Getting started

For end-to-end testing in a JavaScript or TypeScript project, the README's recommended entry point scaffolds a project and configuration:

npm init playwright@latest

Or add the test runner to an existing project and download the browsers manually:

npm i -D @playwright/test
npx playwright install

A first test from the README checks a page title and follows a link, using role-based locators:

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

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

Run the suite. Tests run in parallel across all configured browsers, headless by default:

npx playwright test

Open a recorded trace to see what happened step by step:

npx playwright show-trace trace.zip

On a fresh Linux machine or CI image, the browsers guide shows how to install the browsers together with their OS dependencies in one command:

npx playwright install --with-deps chromium

To generate a test by recording your interactions, start codegen against a URL:

npx playwright codegen demo.playwright.dev/todomvc

For AI agents, the MCP server is configured in an MCP client's settings with npx @playwright/mcp@latest as the command, and the README gives a one-liner for Claude Code:

claude mcp add playwright npx @playwright/mcp@latest

The agent-oriented CLI installs globally:

npm install -g @playwright/cli@latest

To add the planner, generator and healer test agents to a project for a given agent loop, the agents guide uses commands such as npx playwright init-agents --loop=claude (with variants for VS Code, Codex and OpenCode), and says these definitions should be regenerated whenever Playwright is updated. For plain scripting, npm i playwright installs the library.

Running in CI

The CI guide says that when you scaffold with npm init playwright@latest or the VS Code extension, you are offered a GitHub Actions workflow, written to .github/workflows/playwright.yml. It checks out the repository, installs Node.js and npm dependencies, installs the browsers with their system dependencies, runs the tests, and uploads the HTML report as an artifact retained for 30 days. The two Playwright-specific steps are:

npx playwright install --with-deps
npx playwright test

The guide notes that the generated workflow deliberately sets no job-level timeout-minutes; instead it recommends a globalTimeout in the Playwright config so the run fails after a fixed time while reporters can still produce a report. Tests can run on any CI provider, and the same guide covers viewing logs, the HTML report and traces from CI runs.

Use cases

• Cross-browser end-to-end tests. Covering sign-up, checkout or dashboard flows in Chromium, Firefox and WebKit from one suite, with projects for branded Chrome and Edge where that matters.
• CI pipelines with useful failure artifacts. Recording traces on retry, plus screenshots and videos on failure, so a red build comes with a step-by-step replay instead of a stack trace alone.
• Authenticated test suites. Logging in once, saving storage state to a file, and reusing it across hundreds of isolated tests.
• Mobile layout checks. Emulating devices such as an iPhone viewport from the device registry to screenshot responsive layouts.
• Documents and screenshots on demand. Using the library to render pages to PDF or capture screenshots in reporting or archiving jobs.
• Network-level testing. Intercepting or aborting requests with page.route to block images, mock APIs or simulate failures.
• Agent-driven browsing. Giving a coding agent or LLM workflow a real browser through MCP or the CLI to reproduce bugs, fill forms or verify a deployed change.
• Bootstrapping tests with AI. Using the planner, generator and healer agents to draft a test plan, turn it into specs, and keep them passing as the UI changes.

How it compares

The Playwright docs include migration guides from Puppeteer and Protractor. The Puppeteer guide says the APIs have similarities and most Puppeteer APIs can be used as is, but recommends replacing ElementHandle usage with locators and web-first assertions, and notes you probably no longer need explicit waits. There is also an experimental Selenium Grid integration that lets Playwright launch Google Chrome or Microsoft Edge on a Selenium 4 Grid Hub; the docs warn it may break in the future and should be weighed carefully. Compared with Puppeteer-style libraries focused on Chromium, Playwright's distinguishing points are first-class Firefox and WebKit support from the same API and a bundled test runner with isolation, parallelism and tracing. Compared with Selenium and WebDriver-based stacks, Playwright downloads and pins its own browser builds per version rather than relying on separately installed browsers and drivers; that makes setup reproducible, but it also means you are testing patched Firefox and WebKit builds rather than the exact branded browsers your users run.

On the agent side, the project itself compares its two agent interfaces: the MCP server suits MCP clients and LLM-driven automation, while the CLI is presented as more token-efficient for coding agents. Which one fits depends on whether your agent host speaks MCP and how much context budget you can spend on tool schemas and page snapshots.

Things to know before adopting

• System requirements. The JavaScript intro lists Node.js 22.x, 24.x or 26.x; Windows 11+, Windows Server 2019+ or WSL; macOS 14 Sonoma or later; and Debian 12/13 or Ubuntu 22.04/24.04/26.04 on x86-64 or arm64.
• Pinned browser binaries. Each Playwright version needs specific browser builds, so upgrading Playwright usually means re-running npx playwright install. The browsers are cached per OS (for example ~/.cache/ms-playwright on Linux) and the docs show them taking a few hundred megabytes each.
• Patched Firefox and WebKit. Playwright does not work with branded Firefox or Safari. The docs suggest running WebKit on a Mac for the closest-to-Safari experience, and warn that features such as media codecs vary by OS.
• Chromium runs ahead. By default Playwright uses open-source Chromium builds, which the docs say are typically one version ahead of the Chrome and Edge your users have; use the chrome or msedge channels if you need to test branded builds.
• Docker caveats. The official Docker image is intended for testing and development only and is not recommended for visiting untrusted websites. It runs browsers as root by default, which disables the Chromium sandbox; for untrusted sites the docs recommend a separate user plus the provided seccomp profile. They also recommend --ipc=host to keep Chromium from running out of memory, and --init to avoid zombie processes.
• Test agents depend on your tooling. The agents guide notes VS Code v1.105 or newer is needed for the agentic experience in VS Code, and that generated agent definitions should be regenerated after each Playwright update.
• Different runners per language. All languages share the same browser automation core, but the testing ecosystem differs: Node.js has Playwright Test, Python recommends the pytest plugin, Java works with JUnit or TestNG, and .NET provides MSTest, NUnit and xUnit base classes.
• Upgrades move browsers too. Because each Playwright version pins its own browser builds, upgrading the package also changes the browser versions your tests run against, so pin the Playwright version in CI and upgrade deliberately.

Project activity

As of November 2026 the microsoft/playwright repository has about 99,500 stars and around 6,800 forks on GitHub. It was created in November 2019, is written mainly in TypeScript and is licensed under Apache-2.0. The latest release at the time of writing is v1.65.0, published on 5 November 2026, and the main branch receives commits daily. Language bindings live in separate repositories for Python, Java and .NET, and the MCP server, CLI and VS Code extension each have their own repositories under the Microsoft organization.

The source is at github.com/microsoft/playwright, and documentation and the API reference are at playwright.dev.