How to Set a Viewport Size in Applitools Eyes

In a Selenium Java test, set the page viewport by passing a RectangleSize to eyes.open. Assign the returned driver and use it for the rest of the test:

driver = eyes.open(driver, "Applitools", "Test Web Page", new RectangleSize(1024, 768));

The width and height describe the page’s inner content area, not the outside dimensions of the browser window. Eyes calculates the outer window size needed to produce that viewport. Set it near the beginning of the test so the page’s responsive layout is consistent when visual testing starts.

1. Set the viewport in Selenium Java

Import RectangleSize and call the four-argument eyes.open overload:

import com.applitools.eyes.RectangleSize;

// Keep your existing WebDriver setup and Eyes configuration.
// Assign the returned driver and use it for subsequent actions.
driver = eyes.open(driver, "Applitools", "Test Web Page", new RectangleSize(1024, 768));

// Continue interacting with the returned driver, then run your visual check.
driver.get("https://example.com");
eyes.checkWindow("Home page");

This snippet assumes driver and eyes have already been initialized using the Selenium Java SDK setup for your project. The viewport example and instruction to use the returned driver are documented in the Applitools Selenium Java quickstart.

Why use the returned driver?

eyes.open returns the WebDriver instance that should be used for the rest of the test. Reassigning it keeps the test actions attached to the visual test session. Place the call before navigating or interacting with the page so the target viewport is in effect for the page under test.

2. Understand viewport size versus window size

A viewport is the visible page content area where the browser lays out the document. A browser window also includes browser chrome such as tabs and toolbars. Consequently, a requested viewport of 1024 × 768 does not mean the outer browser window is 1024 × 768. Eyes accounts for the difference when it sets the size.

This is why setting Selenium’s outer window dimensions is not interchangeable with passing a viewport to eyes.open. If the test requirement is a particular page layout width and height, specify the viewport through Eyes.

3. Choose dimensions for the layouts you need to verify

Use dimensions that correspond to the layouts your application supports or that your visual checks need to cover. The 1024 × 768 value is an example, not a required default. A fixed viewport helps make repeated captures comparable; multiple viewport sizes help exercise responsive breakpoints.

Test goal	Approach
Repeat the same visual check consistently	Use one deliberate width and height for that test.
Check responsive layout changes	Run visual checks at dimensions representing the relevant layouts or breakpoints.
Match a known rendering issue	Use the viewport dimensions at which the issue was observed.

To find the current page viewport, inspect it in the browser’s JavaScript console (for example, the inner width and height) or use a viewport-size page. Applitools also recommends identifying the page client area rather than treating the browser’s outer window as the viewport.

4. Grid and emulated-device runs

Do not assume that the local Selenium eyes.open viewport argument configures every cross-browser or device-grid run. Applitools’ Java Ultrafast Grid quickstart configures desktop browsers and emulated devices separately through Configuration.addBrowsers, DesktopBrowserInfo, and ChromeEmulationInfo. Follow the guide for the SDK and execution flow in use rather than copying local WebDriver sizing syntax into a grid setup.

Applitools provides separate guides for different SDK families, including Selenium and Playwright. Confirm the applicable guide when your test uses a non-Java binding or a grid workflow.

5. Troubleshoot viewport sizing failures

Symptom or cause	What to check	Possible fix
Eyes cannot create the requested viewport because the calculated outer window exceeds available screen space	Compare the requested viewport and browser setup with the available display dimensions.	Choose a viewport that fits the available screen, or run in an environment with sufficient screen space.
The requested viewport is below the browser’s supported minimum	Check whether the width or height is unusually small for the browser.	Use dimensions at or above the browser’s supported minimum.
Appium on a mobile device fails to apply the requested size	Check whether the mobile window is already maximized.	Use the mobile device or emulation configuration supported by the relevant SDK flow instead of applying the desktop sizing example unchanged.
On Windows, the requested size calculation fails	Check Windows display scaling.	Applitools identifies display zoom other than 100% as a possible cause; use 100% scaling and retry.
WebDriver window sizing succeeds, but the Eyes viewport request fails	Confirm whether the code is setting outer window size or page client-area size.	Use the viewport parameter to eyes.open when the requirement is the page content dimensions.

Applitools documents that an inability to set the requested viewport can throw an exception and stop the test before it proceeds. Treat this as a setup failure: correct the dimensions or environment before interpreting the visual result.

6. Or skip the browser setup

For a screenshot rather than an Applitools visual test, ScreenshotNeo accepts a URL and viewport dimensions in one API request. Its API docs cover the request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -d width=1024 -d height=768 -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://stripe.com",
        "width": 1024,
        "height": 768,
    },
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com',
  width: '1024',
  height: '768',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.

Get 1,000 screenshots a month free with no card.

7. Performance, reliability, and cost considerations

For Applitools, choose only the viewport sizes needed to cover the layouts under test; each additional size is another environment or visual check in your test design. A stable, explicit viewport makes comparisons easier to reproduce, while an unsupported size or display environment can stop the test before checks run. Consult your Applitools plan and SDK configuration for any account-specific execution limits or costs.

For ScreenshotNeo, the API returns an image or PDF from a URL request, and its billing rules distinguish clean shots from bot checks, blank pages, failed loads, timeouts, and cache hits. Those cases cost nothing, with response headers indicating the page verdict and whether the request was billed. ScreenshotNeo offers caching with a configurable TTL; use it when an unchanged page can reuse a prior capture. Plan limits and current feature details are listed on the docs site.

FAQ

Does 1024 × 768 mean the whole browser window?

No. It is the page viewport (content area). Eyes computes the outer browser dimensions needed to reach it.

Can I use a different size?

Yes. Pass the width and height that match the application layout or responsive state you want to verify.

Should I set the viewport before or after navigating?

Set it in eyes.open at the beginning of the test, before the page actions you want to capture.

Does this exact Java syntax configure Ultrafast Grid devices?

Do not assume so. Grid browser and emulated-device environments are configured through the grid configuration documented for that SDK flow.