Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 35 ยท Browsers and Scale

Headless Mode and Browser Options

Configure Chrome, Firefox and Edge in Selenium: headless mode, window size, proxies, profiles, page load strategy and the W3C capabilities behind options.

By default, Selenium opens a normal browser window, runs your script and closes it. That is great while you write a test and a poor fit for a build server that has no screen, or for a laptop where you want to keep working while hundreds of tests run. Browser options let you change how the browser starts: hide the window, set its size, route traffic through a proxy, load a profile or accept a self-signed certificate. This lesson shows the options classes of the main browsers and explains what actually goes over the wire when you use them.

Real browsers cannot run on this site, so Selenium code here is read-only. The runnable examples are stand-ins: an options builder that produces the same kind of JSON capabilities the real library sends, and a validator that catches common mistakes. Argument names are real, but check the documentation of your browser version because flags change.

What options control

Headless Run without a visible window.
Window size Same layout on every machine.
Proxy Route traffic where you choose.
Profile Start with known settings.

Options become capabilities in the new-session request.

1 / 2

The options classes

Each browser has its own options class, and all of them share a base of standard settings. You create the object, change it, and hand it to the driver:

Python
# read-only (Python)
from selenium import webdriver

options = webdriver.ChromeOptions()
options.add_argument("--window-size=1366,768")
driver = webdriver.Chrome(options=options)
Java
// read-only (Java)
ChromeOptions options = new ChromeOptions();
options.addArguments("--window-size=1366,768");
WebDriver driver = new ChromeDriver(options);

Firefox uses webdriver.FirefoxOptions() and Edge uses webdriver.EdgeOptions(). Edge is built on Chromium, so most of Chrome's arguments work there too.

Headless mode

A headless browser has no visible window, but it still renders pages, runs scripts and takes screenshots. It is common in continuous integration, where the machine has no display. For Chrome, the modern flag is --headless=new, which runs the same browser code as normal Chrome (the older headless mode was a separate implementation with differences). Firefox uses -headless.

Python
# read-only
chrome_options = webdriver.ChromeOptions()
chrome_options.add_argument("--headless=new")

firefox_options = webdriver.FirefoxOptions()
firefox_options.add_argument("-headless")

Headless mode uses a default window size that may be smaller than you expect, and responsive pages react to that size. Always set the window size explicitly in headless runs, with --window-size=1280,800 for Chrome or driver.set_window_size(1280, 800) after startup. Otherwise a layout change may hide a menu and make a test fail only on the build server. Failures that appear in headless but not in headed mode usually come from size, missing fonts, or timing, so keep both modes available for debugging, as the flaky tests lesson recommends.

Other useful settings

A few options come up again and again:

  • Page load strategy. options.page_load_strategy = "eager" makes driver.get return when the document is interactive, not when every image has loaded. The values are normal (the default), eager and none. Faster, but your waits must now be correct (see Why Tests Need Waits).
  • Insecure certificates. options.accept_insecure_certs = True lets tests visit a staging site with a self-signed certificate. Use it only for test environments.
  • Binary location. options.binary_location = "/opt/chrome-beta/chrome" points to a specific browser install, for example a beta channel.
  • Proxy. options.add_argument("--proxy-server=http://proxy.internal:8080") in Chrome, or the standard Proxy object, which becomes a proxy capability that every browser understands:
Python
# read-only
from selenium.webdriver.common.proxy import Proxy, ProxyType

proxy = Proxy()
proxy.proxy_type = ProxyType.MANUAL
proxy.http_proxy = "proxy.internal:8080"
proxy.ssl_proxy = "proxy.internal:8080"
options.proxy = proxy
  • Preferences. Chrome takes them through options.add_experimental_option("prefs", {...}), for example a download directory. Firefox uses options.set_preference("intl.accept_languages", "en-US").
  • Profiles. --user-data-dir=/path makes Chrome use a specific profile directory. A fresh profile per run is usually best, because a shared profile carries cookies and cache from one test to the next and makes results depend on history. Use a prepared profile only when you need one, such as an installed extension, and copy it for each run.

Do not paste a long list of flags from the internet. Every extra flag is another difference from what your users run. A good starting set for CI is: headless, an explicit window size, and a few container flags such as --no-sandbox (needed only when Chrome runs as root inside a container; it lowers security, so only use it in disposable CI containers) and --disable-dev-shm-usage (helps when /dev/shm is small in Docker).

From options to capabilities

When you start a session, Selenium sends a "new session" request to the driver. The options become capabilities inside it. The standard ones (browserName, pageLoadStrategy, acceptInsecureCerts, proxy) sit at the top, and browser specific settings go under a vendor key: goog:chromeOptions for Chrome, moz:firefoxOptions for Firefox and ms:edgeOptions for Edge. The prefix and colon follow a W3C rule for extension capabilities.

The request body has this shape:

JSON
{
  "capabilities": {
    "alwaysMatch": {
      "browserName": "chrome",
      "pageLoadStrategy": "eager",
      "goog:chromeOptions": { "args": ["--headless=new", "--window-size=1280,800"] }
    }
  }
}

alwaysMatch lists what must be satisfied. The standard also allows firstMatch, a list of alternatives the driver tries in order. Selenium Grid uses the same capabilities to choose which machine can run your session, which is why understanding this JSON pays off later.

The first stand-in builds that structure from simple method calls.

JS Build W3C capabilities from options

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The same builder pattern exists in the real classes, which also return the options object so you can chain calls in some languages.

Check options before you rely on them

A wrong option often fails silently or only on one machine. The second stand-in is a small validator that applies the lessons above: it warns about headless runs without a window size, a shared profile and risky flags.

JS A tiny options validator

Press Run (or Ctrl + Enter) to see the console output here.

No output.

A habit worth building: one place for browser setup

Create the driver in one function or fixture, read choices such as the browser and headless flag from configuration (see Test Data and Configuration), and keep option lists short and commented. Then a developer can run tests visibly on a laptop and a pipeline can run them headless without changing any test. In pytest this is a fixture (see Selenium with pytest), and when you move to remote machines the same options travel with you, as shown in the next lesson.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which Chrome argument starts the modern headless mode?

    --headless=new runs the same browser code as normal Chrome without showing a window.
  2. 2. Why should you set a window size in headless runs?

    A default size that is smaller or larger than expected can hide or move elements and cause failures only on the build server.
  3. 3. Where do Chrome specific settings go in the W3C new-session request?

    Vendor settings use a prefixed extension capability. Chrome uses goog:chromeOptions, Firefox moz:firefoxOptions and Edge ms:edgeOptions.
  4. 4. What does page_load_strategy = 'eager' do?

    Eager returns when the DOM is ready for interaction. It is faster but makes correct explicit waits more important.
  5. 5. Why is a shared browser profile directory risky for tests?

    Leftover state makes tests order dependent and flaky. A fresh profile per run keeps them independent.

Summary

  • Options classes (ChromeOptions, FirefoxOptions, EdgeOptions) change how a browser starts and become capabilities in the new-session request.
  • Use --headless=new (Chrome and Edge) or -headless (Firefox) on machines without a screen, and always set the window size.
  • Standard capabilities such as pageLoadStrategy, acceptInsecureCerts and proxy work across browsers; vendor settings sit under keys like goog:chromeOptions.
  • Prefer a fresh profile per run, keep flag lists short, and treat --no-sandbox and insecure certificates as test-environment only.
  • Build the driver in one place so the same tests run visibly on a laptop and headless in CI.

Next: Selenium Grid