Two headless modes, two binaries#
We launched Playwright 1.63's Chromium two ways and read what each reported:
| Launch | navigator.userAgent | fullVersionList brands |
|---|---|---|
chromium.launch() | HeadlessChrome/157.0.8103.78 | Not-A.Brand, HeadlessChrome, Chromium |
chromium.launch({ channel: 'chromium' }) | HeadlessChrome/153.0.0.0 | Chromium, Not_A Brand |
The default launch used Playwright's separate headless shell, a lighter binary that reported a full version in its user-agent string. In our environment it also reported a different version number from the full Chromium build installed beside it, so record the version from the browser that actually ran. The chromium channel ran the full browser in Chrome's new headless mode, which shares its code with headed Chrome and reported the reduced user-agent string a normal Chrome sends. Playwright: Chromium new headless mode
Both still carried HeadlessChrome in the user-agent string. A site, a bot filter or a CDN rule that checks for it can serve a headless browser different content.
Differences worth testing, one at a time#
| Difference | Check |
|---|---|
| Binary and mode | Rerun with channel: 'chromium', then headless: false |
| User agent | Set userAgent to the reporter's string and compare the server's response |
| Window and viewport size | Set viewport to the reporter's innerWidth and innerHeight. Headless and headed defaults differ from a typical desktop window. |
| Focus | A headless page can have focus when a real window would not, and the reverse. Bugs that vanish with DevTools open covers focus-dependent code. |
| GPU and graphics | Headless often renders without a GPU. Canvas, WebGL and video can behave differently. |
| Fonts | A Linux CI image has different fonts from a laptop, which changes text width and wrapping |
| Bot detection | A response that differs only for HeadlessChrome. Compare the HTML the server returns. |
The first row splits most cases, with one caution: compare the two headless modes at the same browser version. In our environment they reported different versions, so a difference between them could also be a change between versions. With versions matched, if the new headless mode reproduces and the shell does not, the cause is in what the shell leaves out. If neither headless mode reproduces and headed does, the cause is in focus, window size, the GPU or something the server decides from the request.
Report which browser ran#
A CI log that says "Chromium headless" leaves out the version and the mode. Print them at the start of the run:
console.log(browser.version(), await page.evaluate(() => navigator.userAgent));
Worked example: a sign-up page that a CI test could not see#
This example is fictional. A Playwright test for sign-up passes on developers' machines in headed mode and fails in CI, which runs headless. The test waits for a Create account button that never appears.
The CI trace shows a different page: a "Please verify you are human" challenge. The CDN's bot protection treated HeadlessChrome in the user-agent string as automated traffic. Setting userAgent to a normal Chrome string made the CI run pass, which confirmed the cause. The team then allowed the CI runner through the challenge for its staging environment, rather than spoofing the user-agent string in the test.
Questions#
Should reproductions always run headed?
Run a reproduction where the reporter saw the bug, which is usually headed. Then run it headless to see whether it is portable to CI. A difference between the two is evidence, not noise.
Does headless: false need a display?
Yes. On a Linux server without one, run it under a virtual display such as Xvfb.
Can a site detect new headless mode?
The user-agent string still says HeadlessChrome, and other signals exist. If the bug depends on detection, treat it as a server-side decision and compare the responses.
Return to reproducing what someone else saw for the other layers a replay needs.