Playwright headless vs headed rendering: what actually differs in 2026

What changed when Playwright switched to --headless=new

The old headless mode (now reachable as --headless=old) was a separate Chromium binary path: no compositor, no GPU process, a stripped-down paint stack designed for server use cases where nobody was going to look at the output. That mode rendered text with a different font fallback chain, declined some media APIs entirely, and used software-only canvas. If your test exercised any of those, the headless run could diverge from the headed run for real reasons, not just timing.

The new headless mode is the same Chromium binary booted without a visible window. The compositor still runs. The GPU process still runs (on hardware that has a GPU). The paint output is the same code path that produces what you see in headed. Playwright started passing --headless=new by default in 1.42 (February 2024), and Chromium itself has been slowly removing the old code path since. The practical effect is that most tests that used to flake on the headless versus headed axis no longer do, because the renderer they targeted has been unified.

Most of the rendering-difference guides on the internet predate this change. They will tell you that headless paints text differently (true in 2020, mostly not in 2026), that headless ignores GPU acceleration (true in 2020, not in 2026 on a runner with drivers), and that headless and headed produce different screenshot bytes (true in 2020, hit-and-miss in 2026 depending on the four categories below). Treat the older advice as historical, not current.

The four cases where a real difference still shows up

With the renderer unified, the surface area of legitimate headless versus headed disagreement collapses to four categories. If your test does not exercise any of them, you should be running headless by default and treating headed as a debugger.

1. Visual regression. If your baseline image was captured headed and the runner re-shoots headless on a different OS with different system fonts, you can get false diffs from font fallback, anti-aliasing, and subpixel positioning. The right fix is to bake the runner image (a single Docker image with one font set, one rendering config) and capture the baseline against that same image. Not headless versus headed; runner versus runner.
2. Video element behavior. Autoplay policy, picture-in- picture, media session APIs, and EME (encrypted media) can behave differently in headless because no real audio output device is attached. If your test asserts on a video that plays, pauses, and mutes itself, run it headed or pass the relevant --autoplay-policy=no-user-gesture-required flag.
3. Canvas and WebGL. On a CI runner without GPU drivers, Chromium falls back to SwiftShader, Google's software GL implementation. SwiftShader is correct but byte-different from hardware-accelerated rendering. If you are running pixel comparisons against canvas or WebGL output, expect drift across runner generations even within headless.
4. GPU-accelerated animations. CSS transforms, opacity transitions, and filters that the compositor can run on the GPU will flush frames at different times depending on whether a real GPU is present. A test that asserts on an in-flight transition (rare, but it happens) can see a different intermediate state in headless on CPU compositing than in headed on GPU.

Why an AI agent does not care which mode you picked

Most of the headless versus headed discourse assumes the test author is writing CSS selectors against the DOM and asserting on rendered state. In that world, paint matters: if the locator falls back to a layout-based heuristic, or the assertion compares a rendered region to a baseline, the renderer is part of the test. In an accessibility-tree-driven pipeline, the locator step never reads pixels. The agent calls a snapshot primitive, gets back a tree of interactive nodes annotated with refs, and picks one by label. The browser's rendering pipeline never enters the loop.

The diagram below is the loop Assrt runs for one click step, traced through the actual code paths. The four boxes are the same whether the underlying Chromium was started with --headless or without it. The only line of code in the entire stack that branches on the mode is browser.ts line 366, which decides whether to insert --headless into the argv passed to @playwright/mcp. Nothing downstream knows or cares.

Anchor fact: the exact line that flips the mode in Assrt

A common reaction to claims like "the mode does not matter" is to assume marketing handwave. Here is the part that is not. Assrt spawns @playwright/mcp as a child process over stdio. The argv it assembles starts at browser.ts line 296: [cliPath, "--viewport-size", "1600x900", "--output-mode", "file", "--output-dir", outputDir, "--caps", "devtools"]. Headless versus headed is decided sixty-eight lines later, at line 366:

// /Users/matthewdi/assrt-mcp/src/core/browser.ts:363-368
// --headless conflicts with --cdp-endpoint (and --extension), so only apply
// it in the local-launch path.
if (!extension && !cdpEndpoint) {
  if (!headed) args.splice(1, 0, "--headless");
  console.error(`[browser] launch mode: ${headed ? "headed" : "headless"}`);
}

That is the entire mode decision. One conditional, one argv splice, one log line. Everything else in the agent loop (the snapshot primitive at agent.ts line 956, the action primitives, the video recording pipeline, the per-step screenshot capture) calls into the same @playwright/mcp interface in both modes. The CLI surface is equally minimal: --headed on the command line, or ASSRT_HEADED=1 in the env, or headed: true on the MCP call. Default is headless.

The reason this matters for the broader question is that it bounds how much the mode can possibly affect a test. If the only line that differs is which flag goes into the child process argv, and the child process is the same binary in both cases, the only differences you can see downstream are differences Chromium itself produces from that flag. Those differences are the four categories listed above, and in 2026 they are smaller than the rest of the internet implies.

The two eras of this question, side by side

A useful way to see how the advice has moved is to look at the same question framed in 2020 and again in 2026. The components of the answer are the same; the weights are not.

How to set the mode in real code

Plain Playwright takes headless: true | false as a launch option, or you can pass channel: "chrome" to use installed Chrome instead of the bundled Chromium. The relevant API surface is browser.launch() for the test runner and browserType.launchPersistentContext() for a profile-backed run. The default of headless: true maps to --headless=new; explicitly passing args: ["--headless=old"] opts you back into the legacy mode if you have a specific reason to reproduce 2020-era behavior.

With @playwright/mcp (which is what an AI-agent stack like Assrt calls), the surface is even smaller. The MCP CLI accepts --headless as a positional argv. Pass it in for headless; omit it for headed. Assrt's wrapper around that, as described above, is --headed on the CLI or ASSRT_HEADED=1 in the env. The viewport is locked at 1600x900 in both modes so layout-based tests do not have to be re-baselined when you toggle.

A practical decision rule

You can compress the whole question into three lines. Default to headless. Run headed locally when you want to watch the agent step through a scenario, or when one of the four categories above is the target of your test. Treat any flake that looks mode-dependent as a timing or font or runner-image problem first, and only suspect the renderer after you have ruled those out. In a year of running Assrt against real apps, the count of bugs we ultimately traced to a headless versus headed difference is small enough that the rule has held for almost every run.

Frequently asked questions