Headless browser

A headless browser loads pages, runs JavaScript, builds the DOM and handles network requests exactly like a normal browser, but it draws nothing to a screen. Tests drive it through the same automation protocol as a headed browser. Because it needs no display server, it is the default way to run UI tests in CI containers and build agents.

Example

Playwright runs headless by default. You opt in to a visible window when debugging:

npx playwright test            # headless
npx playwright test --headed   # show the browser
npx playwright test --ui       # interactive UI mode

In Selenium 4 you ask for headless mode through the browser options:

ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new");
WebDriver driver = new ChromeDriver(options);

FirefoxOptions options = new FirefoxOptions();
options.addArguments("-headless");
WebDriver driver = new FirefoxDriver(options);

Why it matters

• It runs anywhere. Build agents and Docker containers usually have no display, so headed runs would need a virtual framebuffer.
• It uses fewer resources than a headed browser, so you can run more workers in parallel on the same machine.
• It is a real browser. Modern headless Chrome and Firefox use the same rendering engine as their headed versions, which is why tests written headless generally behave the same headed.

Common pitfalls

• Viewport differences. A headless browser may start with a different default window size from your desktop browser. Set the viewport explicitly so responsive layouts behave consistently.
• “Works headed, fails headless.” This is usually timing, not headless mode itself: the headless run is faster or slower and exposes a missing wait. Capture a trace or screenshot on failure rather than switching CI to headed.
• Debugging blind. Turn on screenshots, video or traces for failed tests so you can see what the headless browser saw.
• Confusing headless with “not a browser”. Tools that only fetch HTML, without running JavaScript, are not headless browsers and cannot test a modern single-page app.