In Selenium, why does a headless run render a responsive page at a different layout than your headed run?

## Why the two runs disagree A **responsive page** picks its layout from the **CSS viewport width** the browser reports, never from the machine the test runs on. That viewport comes from the browser window. In a **headed** run the operating system's **window manager** creates a real window and sizes it - typically somewhere near your monitor, and often larger still if something in your setup maximised it. In a **headless** run there is no desktop and no window manager at all, so the browser opens its own off-screen window at a **fixed built-in default** and lays the page out there. Nothing in Selenium 4 changes that default on your behalf. The client asks the remote end for a session, the browser decides how big its window is, and the page reflows accordingly. - In Chrome, including `--headless=new`, the headless default has long been **800 x 600**, whatever monitor is attached. - Firefox likewise starts headless at its own fixed default rather than at the screen size. - The number belongs to the **browser**, not to Selenium, so it can move between browser versions - which is precisely why a suite must not lean on it. - Continuous-integration machines usually have no display server either, so "it works on my machine" and "it works in the pipeline" are two different viewport widths. ## What it costs a warehouse stock-count grid Take a stock-count grid that lists one row per bin with the columns SKU, bin, expected, counted and variance while the viewport is at least 1100 px wide, and collapses to one stacked card per bin below that, with variance tucked behind a toggle. Headed at 1600 px your run sees the table. Headless at 800 px it sees cards. What reaches you is a `NoSuchElementException` on the variance cell. That message says nothing whatsoever about width, the stack trace points at a locator that is perfectly correct, and the failure screenshot shows a rendering of the count sheet nobody on the team has ever looked at. Engineers routinely spend an afternoon on this before someone thinks to print the viewport. ## Two places to set the size, and they are not equivalent | | `--window-size=1600,1200` at launch | `manage().window().setSize(...)` afterwards | |---|---|---| | When it applies | before the browser paints anything | after the session exists, usually after a page has loaded | | What the page sees | its first and only layout, already at the target | a **resize**: the page reflows and a `resize` event fires | | Typical failure | the argument's spelling is browser-specific | anything computed at load already used the old width | | Where it lives | the browser options passed at session creation | test setup code, once per session | The launch argument is browser-specific: Chrome and Edge take `--window-size=W,H`, while Firefox takes separate `--width` and `--height` arguments. The Selenium call is the portable one, because it goes through the W3C **Set Window Rect** command that every conforming driver implements. The practical difference is *when*. A stock-count grid that measures its own container in a load handler and caches a column count will keep the narrow decision after a later resize, because the measurement already ran. A grid driven purely by CSS media queries reflows happily either way. ## Making the width an explicit input 1. Decide the one width the suite claims to test, and write it down in a single place rather than in each test. 2. Apply it **at launch**, so the first paint is already correct and no load-time measurement sees the default. 3. Assert it once at the start of the run by reading the real viewport, and fail with a clear message if it is wrong. 4. Use the same width when debugging headed, so what you watch and what CI runs are the same layout. ## Confirming what the page actually got Two different numbers are available, and mixing them up is the second-most-common version of this bug: - `driver.manage().window().getSize()` returns a `Dimension` describing the **whole browser window**, chrome included. - Executing `return window.innerWidth;` in the page returns the **CSS viewport** the layout actually used. ```java long viewport = (long) ((JavascriptExecutor) driver) .executeScript("return window.innerWidth;"); if (viewport < 1100) { throw new IllegalStateException("stock-count grid ran at " + viewport + " px"); } ``` One assertion like that turns a mystifying locator failure into a one-line explanation, in every future run.