Selenium Headless Testing

Headless mode runs a browser without opening any visible window on screen. The browser still loads pages, runs JavaScript, and processes clicks exactly like a normal session, only nothing appears visually. Build servers use headless mode since they often have no display screen attached at all.

Diagram: Headed Versus Headless

Headed Mode:
[Browser Window Visible] <-- you see clicks happen

Headless Mode:
[No Window] --> [Browser still runs internally] --> results returned

Enabling Headless Chrome

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

This single argument switches Chrome into headless mode before the browser even launches.

Enabling Headless Firefox

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

Why Teams Use Headless Testing

• Headless tests run faster since the browser skips rendering pixels to a screen.
• Build servers without a monitor or display driver can still run full test suites.
• Multiple headless browsers run simultaneously using fewer system resources than visible windows.

Setting Window Size In Headless Mode

Headless browsers default to a small window size, which can break responsive layouts during testing. Setting an explicit size avoids this problem.

options.addArguments("--window-size=1920,1080");

This forces the headless browser to behave as if displayed on a standard desktop monitor.

Debugging Headless Failures

Since nothing appears on screen, debugging a headless failure relies heavily on screenshots and logs rather than watching the browser directly.

TakesScreenshot ts = (TakesScreenshot) driver;
File screenshot = ts.getScreenshotAs(OutputType.FILE);
FileUtils.copyFile(screenshot, new File("./headless-debug.png"));

Capturing a screenshot at the failure point recreates the visual context a tester would normally see in headed mode.

Running Both Modes During Development

Many teams write tests in headed mode first, watching the browser to confirm each step works as expected. Once the test passes reliably, switching to headless mode for the automated pipeline keeps development easy while keeping the production runs fast.

Limitations Of Headless Mode

Certain browser extensions and plugins do not load properly in headless mode. Some visual bugs, like a misaligned button only visible to the human eye, remain harder to catch without screenshots at every step. Headless mode also occasionally renders fonts slightly differently than the headed version of the same browser.

Practical Example

A nightly build pipeline runs 200 Selenium tests against the course website using headless Chrome on a Linux server with no monitor attached. The full suite finishes in twelve minutes headless, compared to nineteen minutes when the same tests ran in headed mode during earlier development.