How to Set Browser Window Size for Selenium Screenshots in Java
Set Selenium’s Java window size with `setSize`, then verify the effective viewport in your browser environment before capturing screenshots.
Set the requested browser window size through Selenium’s window manager:
driver.manage().window().setSize(new Dimension(1024, 768));Import org.openqa.selenium.Dimension. This sets the outer window dimensions, not a guaranteed page viewport size. Browser chrome and the operating system affect the space available to the page, so verify the effective viewport in the browser and environment where the screenshot runs. Selenium’s official windows and tabs guide documents the sizing call and screenshot workflow.
Set a fixed window size and capture a screenshot
Call setSize after creating the WebDriver session and before taking the screenshot. The following example assumes Selenium has been added to your Java project and a suitable browser driver is available.
import java.io.File;
import org.openqa.selenium.Dimension;
import org.openqa.selenium.OutputType;
import org.openqa.selenium.TakesScreenshot;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
public class ScreenshotExample {
public static void main(String[] args) {
WebDriver driver = new ChromeDriver();
try {
driver.get("https://example.com");
driver.manage().window().setSize(new Dimension(1024, 768));
File screenshot = ((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);
System.out.println("Screenshot saved temporarily at: "
+ screenshot.getAbsolutePath());
} finally {
driver.quit();
}
}
}OutputType.FILE returns a temporary file managed by the WebDriver implementation. Copy it to your desired output location if you need to retain it. Selenium also supports other screenshot output types, including bytes. The official guide shows the browsing-context screenshot call and documents element screenshots as a separate option.
Choose the right dimensions
- Start the browser session in the same environment used for the capture.
- Navigate to the page and request the outer window dimensions with
setSize(new Dimension(width, height)). - If the requirement is a particular CSS viewport, inspect the actual viewport in that browser. Do not assume the outer window request maps to the same viewport dimensions.
- Wait for the page state your test requires, then capture the screenshot.
The example’s 1024 by 768 values are just a requested outer size, not a universal recommendation or a promise about the resulting image dimensions.
Window size, viewport size, and screenshot size
These are related but distinct measurements:
| Measurement | What it describes | What to verify |
|---|---|---|
| Outer window | The browser window dimensions controlled by Selenium’s window manager. | The requested size and whether the environment accepts it. |
| Viewport | The page area in which browser content is laid out. | The effective viewport in the target browser, including the effects of browser chrome. |
| Screenshot image | The pixels in the saved capture. | The actual file dimensions and the screenshot method’s behavior. |
Selenium’s Java API describes setSize and getSize in terms of the outer window. There is no single conversion from requested outer size to viewport size that applies across browsers and environments. If a test asserts responsive breakpoints, base the assertion on the page’s actual viewport rather than the requested window dimensions.
Fixed size or maximize?
| Method | Use it when | Limitation |
|---|---|---|
setSize(new Dimension(width, height)) |
You need a chosen, repeatable requested outer window size. | The resulting viewport still depends on browser chrome and execution environment. |
maximize() |
You want the window enlarged to fill most of the available screen. | It does not request a particular numeric size, so results depend on the available screen. |
driver.manage().window().maximize();Maximize leaves operating-system menus and toolbars unobstructed. It is convenient for a broad view, but use setSize when your test needs to request specific dimensions.
Capture the page or just one element
Use TakesScreenshot on the driver for a screenshot of the current browsing context:
File pageShot = ((TakesScreenshot) driver)
.getScreenshotAs(OutputType.FILE);If you only need a particular component, Selenium provides a separate element screenshot option:
File elementShot = driver.findElement(By.cssSelector(".report-card"))
.getScreenshotAs(OutputType.FILE);Import org.openqa.selenium.By for the selector example. Element capture is useful when the output should be limited to one located element; setting the window size remains a separate operation.
Repeatable screenshot setup
Screen resolution can affect how an application renders, as the Selenium Project notes in its windows documentation. For visual comparisons, record the browser, driver, operating system or container, and requested window size. Verify the effective viewport and saved image in that target setup. A fixed setSize request alone does not make rendering identical across machines.
- Use the same browser and execution environment for baseline and comparison captures.
- Set the window size before checking responsive layout or capturing.
- Confirm the actual viewport when breakpoints matter.
- Save or inspect the output image dimensions if the delivered pixel size matters.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| The screenshot does not have the requested width and height. | setSize sets the outer window, while the screenshot or page viewport can have different dimensions. |
Inspect the actual viewport and saved image in the target environment; do not infer either from the outer size. |
| The page uses an unexpected responsive breakpoint. | The effective viewport differs from the requested outer window because browser chrome and environment affect available page area. | Check the browser’s actual viewport and adjust the requested window size for that specific setup. |
| The screenshot size changes between machines or runs. | Screen resolution and environment differences can affect rendering and the available window area. | Keep browser, driver, operating system or container, and screen setup consistent; record them with the requested dimensions. |
| The window fills the screen but not a repeatable numeric size. | maximize() fills most of the available screen rather than selecting fixed dimensions. |
Use setSize when you need to request specific outer dimensions. |
| The screenshot file is unavailable after the run. | OutputType.FILE provides a temporary file. |
Copy the file to a persistent destination before the WebDriver session ends or use a byte output type and write it yourself. |
The code cannot resolve Dimension or TakesScreenshot. |
The Selenium imports are missing. | Import org.openqa.selenium.Dimension, org.openqa.selenium.TakesScreenshot, and the output type you use. |
Performance, reliability, and cost
Window sizing itself is a browser configuration step. For dependable visual checks, account for the larger sources of variation: browser and driver versions, screen resolution, the page’s readiness, and the effective viewport. Avoid treating a requested outer size as proof that the page rendered at an exact viewport or image size.
A Selenium workflow runs a browser and requires you to manage its driver and execution environment. That gives your test control over browser interaction, while adding setup and maintenance. For one-off website captures, a screenshot API can avoid managing that browser setup. The cost of a Selenium run depends on your own browser and infrastructure; no universal cost or timing applies.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF. Its API supports viewport and device options, full-page and element captures, and other screenshot settings; see the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed, and each response identifies the page verdict and billing status in headers. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month with no card.
FAQ
Does setSize set the browser viewport?
No. It sets the outer window size. Check the effective viewport when page layout dimensions matter.
Should I size the browser before or after navigating?
Set it before capturing and before making assertions about responsive layout. Applying it after navigation can trigger a layout change, so wait for the page state your capture needs.
Can I use this method with a remote WebDriver?
The call is part of Selenium’s WebDriver window API. The remote browser environment still determines the effective viewport and rendering, so verify dimensions there.
Does a full-page screenshot mean the same thing as a viewport screenshot?
No. A viewport screenshot represents the current browsing context, while full-page capture concerns content beyond the initially visible area. Choose the capture behavior that matches the output you need.
