In Selenium 4, why does driver.getScreenshotAs() capture only the visible viewport rather than the whole page?

## The command behind `getScreenshotAs` When a Selenium 4 test calls `((TakesScreenshot) driver).getScreenshotAs(...)`, `RemoteWebDriver` sends `DriverCommand.SCREENSHOT`, which is the W3C WebDriver **Take Screenshot** command: ``` GET /session/{session id}/screenshot ``` The specification describes screenshots as a diagnostic mechanism that works by **dumping a snapshot of the visual viewport's framebuffer as a lossless PNG image**, returned to the local end as a base64-encoded string. That one sentence is the whole answer: the source of the pixels is the framebuffer — what the compositor has actually painted — not the document. ## Why the whole document never arrives The remote-end steps look, at first glance, as if they should capture everything. They compute **root rect** as the current top-level browsing context's *document element's* rectangle, which for a 40-page merger agreement in a redaction tool is thousands of CSS pixels tall. Then they call the algorithm named **draw a bounding box from the framebuffer**, and that algorithm clamps: 1. if the visual viewport's width or height is `0`, it fails with the error code `unable to capture screen`; 2. **paint width** becomes the visual viewport's width minus `min(rect x, rect x + rect width)`; 3. **paint height** becomes the visual viewport's height minus `min(rect y, rect y + rect height)`; 4. a canvas of exactly `paint width` × `paint height` is created and the framebuffer region is drawn onto it; 5. the canvas is serialised to PNG and base64-encoded. Steps 2 and 3 start from the *viewport's* dimensions, not the rectangle's. However tall the document rect is, the canvas can never exceed the viewport. A request that asks for the whole page comes back cropped to the window. ## What a redaction reviewer actually sees | the assumption | what the spec does | |---|---| | captures the full document top to bottom | clamps the paint rectangle to the visual viewport | | captures whatever context the driver switched into | always the current **top-level** browsing context | | the format is negotiable | always a lossless PNG, base64-encoded | | scroll position is irrelevant | the framebuffer is whatever is painted right now | Concretely, on a page showing a long agreement with a sticky redaction toolbar: - the image contains the toolbar and roughly one screen of clauses, and nothing else; - if the assertion that failed was about clause 47, three screens down, **the evidence PNG proves nothing** — it shows the top of the document; - because the framebuffer is sampled as painted, the current scroll offset silently decides the content of your evidence. ## The frame surprise The spec binds Take Screenshot to the session's *current top-level browsing context*. If the redaction tool renders the document inside an `iframe` and the test has switched into that frame, `getScreenshotAs` still returns the top-level viewport — the switch does not narrow the shot. Candidates routinely expect the opposite, and it is the fastest way to waste an hour wondering why the image looks unchanged. Two error codes are worth recognising: - **`no such window`** — the top-level browsing context is no longer open, typically because a `close()` ran before the capture; - **`unable to capture screen`** — a zero-dimension viewport, or a bitmap the browser refuses to serialise. ## Getting more than the viewport The spec deliberately does not offer a full-page mode, so every route is a workaround: - **A vendor extension.** Firefox exposes a non-standard full-page command through `HasFullPageScreenshot.getFullPageScreenshotAs(OutputType)`; there is no equivalent on Chromium drivers in Selenium 4. - **Scroll and stitch.** Take one shot per viewport-height scroll step and join the slices yourself, accepting the seams that produces. - **Print Page.** `PrintsPage.print(PrintOptions)` is a W3C command (`POST /session/{session id}/print`) that paginates the whole document — but it returns a `Pdf`, not an image. - **A bigger window.** Enlarging the browser enlarges the viewport and therefore the shot; how you size the window is a separate concern from how you capture it. ## The practical discipline Because scope is decided by the command and not by your `OutputType`, an evidence screenshot is only useful if the thing you want to prove is on screen when you take it. In a redaction suite that usually means capturing immediately at the point of failure, in the same run, with the element of interest already scrolled into view — and being explicit in the report that the PNG is one viewport, not the document.