The Illustrated Playwright

Playwright is an open-source browser automation framework created by Microsoft and its contributors. The Illustrated Playwright is an independent reference about how it works inside. It is not official Playwright documentation. Playwright’s design and code belong to its authors; this project adds animated explanations, a reading of the source code, and a comparison of the documentation with the implementation.

Problem

Test engineers use Playwright every day, but its internal behaviour is spread across several layers: the test runner, the client, the protocol, the server, the script injected into the page, and the browser. The documentation describes what to expect. It rarely shows how the parts interact, and in some places the code does more than the documentation says.

Scope

The book explains Playwright internals with one spread per concept. A spread has an animated figure, a few short paragraphs, code insets, the call-log messages a reader can see, and notes where the code differs from or adds detail to the documentation.

It does not teach Playwright from the start and it does not replace the official documentation.

Architecture

• Astro Starlight site, published at illustrated-playwright.metronforge.dev.
• Animated figures are plain TypeScript, CSS and SVG, with no runtime libraries.
• The book uses the MetronForge colours, fonts and logo, and works in light and dark themes and on phones.
• Spread metadata (concepts, API names, call-log messages) feeds the map, the index of terms and the Docs vs. code register.

Current result

The first edition is published. It has 23 spreads: an opening spread on the anatomy of a test and six parts on messages and browser objects, the path from locator to click, request routing and HAR, the test runner, expectations and reports, and tracing and codegen. A map, an index of terms and a Method and sources page complete it.

The Docs vs. code register collects 11 findings: in 2 the code contradicts the documentation, in 9 it shows detail the documentation does not state. One example: spread 2.1, Two loops behind every click, shows that locator.click() resolves the locator, then retries the action on the same element, and checks stable before visible and enabled.

Verification

• Each claim is checked against the Playwright source at tag v1.64.1 (commit cfe490d). Source links point to that tag.
• The analysis is static: it reads source code and documentation. It does not measure running browsers.
• Each spread has a set of claims with source paths, line ranges and verbatim quotes. A script checks every quote against the pinned source.
• Continuous integration runs 315 Playwright browser checks on the book: both themes, phone width, animation, reduced motion, keyboard use, links and contrast.

Reproducibility

Every statement in the book names the Playwright file and line it comes from, at v1.64.1. A reader can open the same lines and check the claim. For example, this shows that the click checks stable before visible and enabled:

git clone --depth 1 --branch v1.64.1 https://github.com/microsoft/playwright
cd playwright
sed -n 693,708p packages/injected/src/injectedScript.ts

Limitations

• The analysis is static: figures are illustrations with example values, not recordings of a run.
• Findings apply to Playwright v1.64.1. Later versions can behave differently.
• The book source is kept in a private repository; only the published build is public.