Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesSet the web page’s viewport, not your operating system’s monitor resolution. In a manually controlled browser, pass viewport: { width, height } to browser.newContext(). In Playwright Test, use use.viewport. For a single page, call page.setViewportSize(), preferably before navigation. Add screen only when the application reads window.screen and must see matching dimensions.
What “screen size” means in headless Playwright
Headless Chromium does not need a special display-size flag for normal responsive-layout testing. Playwright emulates the content viewport—the CSS area in which the page renders. That is different from the physical monitor or the host operating system’s resolution.
Playwright’s documented default viewport is 1280×720. A deterministic test therefore sets the dimensions explicitly rather than relying on the machine running the test. Headless mode is already the default for Playwright launches.
| Goal | Use | When to choose it |
|---|---|---|
| One size across a Playwright Test project or scope | use: { viewport: { width, height } } |
Runner-managed tests |
| One size for every page in a manually created context | browser.newContext({ viewport }) |
Custom scripts and fixtures |
| Resize one page | page.setViewportSize({ width, height }) |
One-off or mid-script changes |
Control values returned by window.screen |
screen together with viewport |
Applications that branch on screen dimensions |
Set a fixed viewport in a headless script
Create the context with the target dimensions before opening the page. This is the most reliable pattern when the initial layout, media queries or JavaScript startup logic depends on the size.
#1 Best Overall
import { chromium } from 'playwright';
const browser = await chromium.launch(); // headless: true by default
const context = await browser.newContext({
viewport: { width: 1440, height: 900 }
});
const page = await context.newPage();
await page.goto('https://example.com');
console.log(await page.evaluate(() => ({
innerWidth: window.innerWidth,
innerHeight: window.innerHeight
})));
await browser.close();The viewport dimensions are CSS pixels. They determine responsive breakpoints and the visible page area; they do not enlarge the host machine’s display.
Match window.screen as well
viewport controls the page viewport. screen emulates the window-screen values exposed through window.screen, and it only applies when a viewport is set. Configure both at context creation when application code compares those values.
const context = await browser.newContext({
viewport: { width: 1440, height: 900 },
screen: { width: 1440, height: 900 }
});This is useful for code that checks screen.width, screen.height or related screen properties. If your page only uses CSS media queries or window.innerWidth, a viewport alone is normally sufficient.
Resize an individual page
Use page.setViewportSize() when the change belongs to one page rather than the whole context.
Free tools Windows power users keep installed
One-click scans. No signup required.
const browser = await chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();
await page.setViewportSize({ width: 1440, height: 900 });
await page.goto('https://example.com');Set the size before goto() when the first render matters. Sites can choose markup, navigation and assets during the initial load, and changing dimensions afterward may not reproduce that first-load behavior.
Changing the page viewport can also reset the emulated screen dimensions. If viewport and screen must remain independently controlled, prefer browser.newContext({ viewport, screen }) instead of repeatedly resizing the page.
Configure Playwright Test
For Playwright Test, put the setting in the project or global use configuration. Every test context created by that configuration receives the viewport.
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
viewport: { width: 1440, height: 900 }
}
});The runner’s default is 1280×720 unless you override it. A test-level or project-level setting can target a narrower scope. Explicit context options take precedence when you create a context yourself.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
import { test, expect } from '@playwright/test';
test('desktop navigation fits', async ({ page }) => {
await page.goto('https://example.com');
await expect(page.locator('nav')).toBeVisible();
});Use a named device preset, then override its viewport
Device descriptors combine viewport and other emulation parameters. Spread the preset first and place your own viewport afterward if you need a different size.
import { chromium, devices } from 'playwright';
const browser = await chromium.launch();
const context = await browser.newContext({
...devices['Desktop Chrome'],
viewport: { width: 1440, height: 900 }
});The order matters: a later viewport property replaces the preset’s supplied viewport.
Generate code at a chosen size
Codegen has its own viewport option. It is useful for producing starter code, but it does not replace runtime configuration in your script or test project.
npx playwright codegen --viewport-size="800,600" https://example.comThe 800×600 values are an example, not a universal recommendation. Choose a size that represents the browser class your test is intended to cover.
Viewport versus screen: practical decisions
- Responsive CSS: set
viewport; media queries respond to the emulated page width and height. - JavaScript layout checks: inspect the values your application uses, such as
innerWidthorclientWidth, and configure the corresponding viewport. - Code that reads
window.screen: setscreenandviewporttogether. - True device behavior: use a device descriptor and override only the properties you intentionally want to change.
- Host-window experimentation:
viewport: nullopts out of consistent viewport emulation and makes the size depend on the host window. That is inherently less deterministic for CI.
Why browser launch flags are usually the wrong fix
Arguments such as --start-maximized manage a browser window, not the deterministic web-content viewport that Playwright exposes through its APIs. Custom browser arguments can also interfere with Playwright’s operation. Prefer context, test, device and page options unless you have a narrowly documented browser-level requirement.
Likewise, changing the operating system’s display resolution is unnecessary for ordinary headless layout tests. It adds machine-level variability without giving your page a more precise viewport contract.
Verify the dimensions inside the page
When a test behaves unexpectedly, print the values the page actually sees.
const dimensions = await page.evaluate(() => ({
innerWidth: window.innerWidth,
innerHeight: window.innerHeight,
screenWidth: window.screen.width,
screenHeight: window.screen.height,
devicePixelRatio: window.devicePixelRatio
}));
console.log(dimensions);Compare these values with the dimensions you configured. A matching viewport does not imply a particular device-pixel ratio; scale and device emulation are separate concerns.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Troubleshooting common sizing problems
The page still uses the old layout
- Set the viewport before
goto()so first-load logic sees the final dimensions. - Check that a later fixture, project, device preset or page resize is not overwriting your setting.
- Reload after a deliberate mid-page resize if the application only computes breakpoints during startup.
window.screen does not match
Set screen alongside viewport on the browser context. A page-level resize is convenient, but it can reset emulated screen dimensions.
CI screenshots differ between runs
- Use an explicit numeric viewport instead of
viewport: null. - Keep browser, Playwright and operating-system versions consistent across workers.
- Wait for fonts, images and application data before capturing; viewport determinism cannot compensate for unfinished rendering.
A custom launch argument appears ineffective
Remove window-management flags and configure viewport or use.viewport instead. If an argument is genuinely required, introduce it only after confirming that it does not override or destabilize Playwright’s emulation.
Mobile behavior is not reproduced by changing width alone
A narrow viewport changes layout, but a device preset may also provide user-agent, touch and other emulation parameters. Start with the appropriate descriptor when the application makes decisions based on more than width.
Performance, reliability and test design
- Configure once: a context-level viewport avoids repeated page resizes and gives every page the same initial conditions.
- Use separate projects for breakpoints: desktop and mobile projects make failures easy to attribute while preserving parallel execution.
- Keep dimensions purposeful: test the breakpoints your product supports rather than generating many nearly identical sizes.
- Capture after stability: wait for the relevant selector, fonts or network state before asserting pixels.
- Record dimensions in failures: logging viewport and screen values turns an ambiguous visual diff into a diagnosable configuration issue.
Or skip the browser setup
If your goal is simply to obtain a clean screenshot at a chosen viewport, ScreenshotNeo provides a website screenshot API. Its request accepts viewport and many other capture options without requiring you to install or maintain a browser.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the complete option list and parameter names.
import 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}`);Before capture, ScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server lets Claude, Cursor and other MCP clients call take_screenshot, get_page_info and capture_pdf. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Does headless mode change the viewport API?
No. The same context, test and page viewport settings apply whether the browser is headless or headed; headless is the documented default.
Can I set only width and let height be automatic?
Playwright’s viewport option takes width and height. Choose both explicitly for reproducible rendering and screenshots.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallIs viewport size the same as screenshot pixel dimensions?
Not necessarily. Screenshot output can also be affected by full-page capture, device scale and image options. The viewport describes the page’s emulated CSS area.
Frequently Asked Questions
Can I change the viewport after a page has loaded?
Yes. Call page.setViewportSize(), then perform whatever reload or application-specific reinitialization your site requires. For first-render behavior, set it before navigation instead.
What should I use for a CI matrix of screen sizes?
Define separate Playwright Test projects with explicit use.viewport values. This keeps each breakpoint deterministic and makes failures attributable to a named project.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
