Playwright: one API for Chromium, Firefox and WebKit, plus a CLI and MCP server for agents

Four entry points, one browser stack

The repository is not one product. The README presents a table of five paths, and the choice between them determines almost everything about how you use the project. Playwright Test is the end-to-end test runner. Playwright CLI is a command-line interface aimed at coding agents such as Claude Code and Copilot. Playwright MCP is a Model Context Protocol server for AI agents and LLM-driven automation. Playwright Library is the plain npm package for scripts: scraping, PDF generation, screenshot capture. The VS Code extension covers authoring and debugging inside the editor.

All of them sit on the same browser automation core, which is why the README can say the project drives Chromium, Firefox and WebKit with a single API. The repository layout reflects that split: packages/ holds the published packages, tests/ holds separate Playwright test configurations for chromium, firefox, webkit, webview, android, electron, installation, stress and bidi, and examples/ contains small runnable projects such as github-api, mock-battery, mock-filesystem, svgomg, todomvc and webauthn.

The internal package.json sets engines.node to ">=20" and declares the licence as Apache-2.0. The version field reads 1.64.0-next, which is the in-development version of the monorepo rather than a published release; the most recent release listed is v1.62.1 from 2026-07-30, with v1.62.0 before it on 2026-07-24 and v1.61.1 on 2026-06-23. The last push to main was on 2026-07-30, so this is a repository with recent activity, but treat the next-version field as a build artefact and not as something you can install.

How auto-waiting and browser contexts change test code

Two mechanisms do most of the work in Playwright Test, and both are visible in the README examples.

The first is auto-waiting with web-first assertions. The README states there are no artificial timeouts: Playwright waits for elements to be actionable, and assertions retry until their condition is met. In the sample test, the click on the "Get started" link is followed by an expectation that a heading named "Installation" is visible. There is no sleep between them. That is the practical difference from frameworks where you insert a wait and hope the page settled.

The second is isolation through browser contexts. Each test gets a fresh browser context, which the README describes as equivalent to a fresh browser profile, with near-zero overhead. That matters for authentication. Instead of logging in before every test, you save storage state once and point other tests at the file. The README gives this example, which writes the state after login and then reuses it.

Installing Playwright and running a first test

The README offers two install routes for the test runner. The scaffold command creates a project with configuration and an example test; the manual route adds the package as a dev dependency and downloads the browsers separately. Both are quoted verbatim below.

npm init playwright@latest

If you prefer to add it to an existing project, install the test package as a dev dependency and then fetch the browser builds. The second command is the one that downloads Chromium, Firefox and WebKit, so it is the step that needs network access in CI.

npm i -D @playwright/test
npx playwright install

Once the browsers are in place, a test file imports test and expect from the test package and drives a page object. The README's example navigates to the documentation site, asserts the title matches, then clicks a link by role and asserts a heading is visible.

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 with the test command. Tests run in parallel across all configured browsers, in headless mode by default, and each test gets a fresh browser context.

npx playwright test

Locators, tracing and the debugging loop

Locators are the part of the API most likely to decide whether your suite survives a redesign. Playwright's locators mirror how a user sees the page rather than how the DOM is structured. The README lists role, label, placeholder and test-id variants: getByRole with a name, getByLabel for a form field, getByPlaceholder for a search box, getByTestId for an explicit hook. Role-based locators survive class renames; test-id locators survive everything but a deliberate attribute change. The trade-off is that role queries depend on correct accessibility markup, so a div with a click handler and no role will not match getByRole('button'), and you will fall back to a CSS selector or add the role yourself.

Tracing is the other half of the debugging story. The README shows a config fragment setting trace to 'on-first-retry', which captures a trace when a test fails on its first retry rather than on every run.

export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

The trace records actions, DOM snapshots, network requests and console messages, and you open it with the trace viewer command shown below. Capturing on first retry keeps artefact volume down; capturing on every run gives you a recording of passing tests too, at the cost of storage. The README does not document a retention or upload policy for those artefacts, so where trace.zip files end up is your decision, not the project's.

npx playwright show-trace trace.zip

The CLI and MCP server: browser control for coding agents

Playwright CLI installs globally and is positioned as more token-efficient than MCP because commands avoid loading large tool schemas and accessibility trees into the model context. In practice you either point an agent at a task in natural language or run the commands yourself.

npm install -g @playwright/cli@latest

The README gives this sequence against the TodoMVC demo: open the page headed, type a todo, press Enter, take a screenshot. The headed flag means you watch the browser rather than running invisibly, which is useful while you are working out a flow and wasteful in a pipeline.

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

There is also a monitoring command, playwright-cli show, which opens a dashboard with live screencast previews of all running sessions; clicking a session zooms in for remote control. The README notes an optional skills install for richer agent integration.

Playwright MCP takes the opposite approach. Instead of shell commands, an agent talks to a server over the Model Context Protocol and sees the page as a structured accessibility tree, with element references it clicks and types into. The README's example snapshot shows a heading, a textbox with a ref, and a list item containing a checkbox and its text. The stated advantage is determinism: the agent acts on refs rather than guessing coordinates from a screenshot, so no vision model is required. The cost is context size, which is exactly the problem the CLI was built to avoid. Choosing between them is a real trade-off, not a preference.

For other MCP clients the README gives a JSON block naming the npx command and its argument, and for Claude Code a single registration command.

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

claude mcp add playwright npx @playwright/mcp@latest

Where Playwright is the wrong tool

Playwright is a browser automation framework, and that is the boundary. If your problem is validating HTTP responses, checking a JSON schema, or load-testing an API, a browser is dead weight: you pay for browser downloads, a Node runtime and a process per worker to test something that never renders. The README does not claim otherwise, and the examples directory is entirely page-oriented.

The heavier constraint is the browser download. npx playwright install fetches Chromium, Firefox and WebKit builds, and the README treats that step as part of installation. On a locked-down CI image, behind a proxy, or on an architecture where a WebKit build is unavailable, that step is where a rollout stalls. The README does not document an offline install path or a mirror configuration, so if your build environment cannot reach the download hosts, verify this before you plan a migration rather than after.

There is also a maintenance cost that the feature list hides. Role-based locators depend on accessible markup, so a suite written with getByRole will break when a component loses its semantics, even if the page still works for mouse users. And because the project spans a test runner, a library, a CLI and an MCP server, teams that adopt more than one of them inherit more than one upgrade path.

Playwright versus Selenium, and the Python question

The comparison people search for is Playwright against Selenium, and the architectural difference is worth stating plainly. Selenium drives browsers through the WebDriver protocol, with a driver process between your test code and the browser. Playwright ships its own browser builds and talks to them directly, which is what makes the auto-waiting and context isolation in the README possible. The consequence is that Playwright's browser support is tied to the builds it distributes, while a WebDriver-based setup can attach to a browser you already have installed, including one on a remote grid. If your organisation already runs a Selenium grid, Playwright does not replace it; it replaces the client side.

On language, the README and the repository are TypeScript, and the package.json is a Node package with engines.node set to 20 or newer. Search interest in Playwright with Python is high, and the project does publish bindings for other languages, but the README here documents the npm install paths and does not document the Python API, its install command or its feature parity. If Python is a hard requirement, check the official documentation site before assuming the examples above translate. The repository also carries a bidi test configuration, which points at WebDriver BiDi work, but the README does not describe what is supported through it.

Licence, upgrades and what a version bump costs

The repository is licensed Apache-2.0, and there is a NOTICE file at the top level alongside LICENSE. Apache-2.0 permits commercial and closed-source use and includes a patent grant; it also requires that you preserve the licence and NOTICE when redistributing. This is a description of the licence text, not legal advice, and if you vendor the browser builds or ship them inside a product, have your own counsel read the terms rather than treating this paragraph as clearance.

Upgrade cost is shaped by the release cadence. The listed releases are v1.61.1 on 2026-06-23, v1.62.0 on 2026-07-24 and v1.62.1 on 2026-07-30, with the last push to main on 2026-07-30. That is a steady minor-release rhythm, and each minor release can change browser versions, which is the part that breaks suites. The README does not document a rollback procedure or a long-term support line, so pinning the package version and the browser build together is the only lever the README supports. Treat the CLI and MCP packages as separate dependencies with their own release timing; installing @playwright/cli or @playwright/mcp alongside @playwright/test does not guarantee they move in step.

Editorial conclusion

Adopt Playwright if you need cross-browser end-to-end tests or want an agent to drive a real browser through the CLI or MCP server. Skip it if you only need HTTP-level checks, or if the WebKit build is a hard requirement on a platform where the download fails and you have no fallback. Before committing, run npx playwright install on the CI image you actually use, confirm Node is at least 20, and decide whether the trace artefacts go into your existing report storage.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes