When a Chrome screenshot changes between headful and headless runs—or looks different in CI—make the browser build, launch mode, viewport, device scale, capture type, and page state explicit before changing CSS or adding delays. Those inputs can change the image even when the page code is unchanged. Work through them in order, then compare screenshots in a controlled environment.
Why headful screenshots differ
“Headful” means launching the browser with a visible UI; it is not a guarantee that its pixels match a headless run. Rendering can vary with the host operating system, browser version and settings, hardware, power source, and headless mode. Playwright’s visual comparison guidance names these as potential sources of variation and recommends using the same environment for creating and checking baselines: Playwright visual comparisons.
The exact browser executable matters, too. Puppeteer defaults to headless mode. Its modern headless and headful modes use Chrome for Testing through the same browser code path, while headless: 'shell' selects the separate legacy headless-shell binary. Playwright likewise distinguishes the regular Chromium build used for headed operations from a separate headless shell used for headless mode. Confirm the actual binary rather than assuming every run called “Chrome” is equivalent. See Puppeteer headless modes and Playwright browser installation.
Same code path is useful, but it does not promise pixel-identical output across modes, machines, or browser versions. Treat the screenshot as the result of the browser plus its environment and the page state at capture time.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Record the run before changing it
Capture enough detail to reproduce both the passing and failing image. Log these values alongside each artifact or visual-test result:
- Automation package and version, browser version, and actual executable or channel.
- Operating system or container image, and whether the run is local or in CI.
- Headful, modern headless, or headless-shell mode; launch arguments and relevant browser settings.
- Viewport width and height in CSS pixels, device scale factor, and screenshot output scale.
- Capture type: viewport, element or clip, or full page; include the options that affect it.
- The readiness condition used and any fonts, data, animations, or changing content involved.
Puppeteer’s supported-browser compatibility table is version-dependent. At the time represented by its current documentation, it maps Puppeteer v25.12.0 to Chrome for Testing 154.0.8037.57; check the live Puppeteer supported browsers table for the mapping applicable to your installed version. A documented version mapping is not a promise that another operating system or capture configuration will render identical pixels.
Check the browser mode and executable
Puppeteer: distinguish modern headless from shell
Puppeteer launches headless by default. Set headless: false for a visible browser. Avoid using headless: 'shell' as a synonym for modern headless: it selects the separate Chrome headless-shell binary and is a distinct comparison target.
const browser = await puppeteer.launch({ headless: false });When a mismatch appears only in headful mode, rerun the same page and capture with the same Puppeteer version and explicit settings, changing only the mode. Save the browser version and executable details for each run. If you change the browser build, mode, and viewport together, the result cannot isolate which difference mattered.
Recommended Free Tools
Rank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
Playwright: verify the installed browser build
Playwright’s browser installation and launch configuration determine which build a run uses. Its regular Chromium and headless-shell builds are not interchangeable assumptions. Check the project’s configured browser/channel and installed browsers using the Playwright browsers guide. Keep that selection the same between baseline creation and CI comparison before adjusting visual thresholds.
Match viewport dimensions and pixel scale
Viewport dimensions and device scale factor are separate settings. Puppeteer viewport width and height are CSS pixels; its deviceScaleFactor sets device scale and defaults to 1. In Playwright, screenshot scale can be 'css' (one output pixel per CSS pixel) or 'device' (one output pixel per device pixel). Playwright documents 'device' as the default, so high-DPI output may be larger than the CSS viewport dimensions. See the Puppeteer Viewport API and Playwright Page API.
If an image is consistently larger or smaller than expected, compare CSS dimensions with actual output pixel dimensions first. A scale mismatch can look like a layout bug. Set viewport width, viewport height, and device scale intentionally, and set Playwright’s screenshot scale where the output needs to be CSS-pixel-sized.
// Puppeteer: CSS-pixel viewport and explicit device scale factor
await page.setViewport({ width: 1280, height: 800, deviceScaleFactor: 1 });
// Playwright: CSS-pixel viewport
await page.setViewportSize({ width: 1280, height: 800 });
// When capturing, choose scale: 'css' or scale: 'device' deliberately.Use the same values for local and CI runs. Do not compensate for a scale mismatch by changing the page’s CSS or by rescaling only one baseline.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
Isolate viewport, element, and full-page capture
A viewport screenshot, a clipped region, and a full-page capture exercise different capture behavior. First reproduce the issue with a viewport screenshot. Then test the failing element or full-page path using the same browser, geometry, and page state. If the viewport is correct but the full-page image is clipped or unexpectedly sized, focus on capture options rather than treating all screenshot APIs as equivalent.
Puppeteer’s screenshot options include fullPage, clip, captureBeyondViewport, and omitBackground. Review their behavior in the Puppeteer ScreenshotOptions API. Playwright supports full-page and clipped capture through its Page screenshot API. An element screenshot may bring the element into view, so check scroll position and resulting page state if the element image differs from the viewport capture.
- For a viewport mismatch, confirm viewport size, scale, and browser mode.
- For a clipped image, verify clip coordinates and dimensions against the page’s rendered geometry.
- For a full-page mismatch, check full-page behavior and content that loads or changes as the page is scrolled.
- For a transparent or unexpected background, check whether the capture option omits the background and whether the page itself supplies one.
Wait for the page state that matters
Arbitrary sleeps hide timing problems and can still capture too early—or too late. Wait for an observable condition tied to the application: a key locator becoming visible, a loading indicator disappearing, required data appearing, or fonts finishing loading. Puppeteer’s screenshot guide demonstrates navigation waiting and selector waits; see Puppeteer Screenshots.
Network quiet is not a universal definition of ready. Pages may keep connections open, fetch data after navigation, or render before every request finishes. Playwright explicitly discourages using networkidle for tests and recommends assertions to assess readiness. For example, wait for the content that the screenshot is meant to show:
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 matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
// Playwright example: wait for meaningful application content
await page.goto('https://example.com');
await page.getByRole('heading', { name: 'Dashboard' }).waitFor({ state: 'visible' });
await page.screenshot({ path: 'dashboard.png' });Adapt the locator to the actual page. If custom fonts or asynchronous content affect layout, wait for those specific conditions as well; a visible shell of the page is not necessarily the final rendered state.
Remove intentional visual variability
Even with the right browser and ready page, animations and volatile content can make consecutive captures differ. Freeze or suppress only the sources that should not be part of the test: transitions, blinking carets, timestamps, rotating banners, or live cursors. Playwright’s screenshot API supports animations, caret, and screenshot-only style options. These are Playwright-specific options; do not assume Puppeteer uses the same names.
// Playwright: disable animations, hide caret, and apply screenshot-only CSS
await page.screenshot({
path: 'stable.png',
animations: 'disabled',
caret: 'hide',
style: `
.timestamp, .rotating-banner, .live-cursor { visibility: hidden !important; }
`,
});Use selectors that target genuinely volatile regions in your own application. Hiding broad containers can conceal a real layout regression. Playwright’s expect(page).toHaveScreenshot() also waits until two consecutive screenshots match before comparing the last image with its expected snapshot; this helps address transient changes, but it does not make different host environments equivalent. See Playwright PageAssertions.
Compare baselines in a controlled environment
Create and check a visual baseline in the same operating system or container, browser build and version, settings, and scale. Playwright’s visual-comparisons guidance recommends matching the environment used for the baseline because host and runtime variables can affect rendering. If a mismatch disappears once the environment is aligned, pin and document that environment rather than relaxing pixel-difference thresholds blindly.
Only adjust a difference threshold after the browser, geometry, capture mode, readiness, and known dynamic content are controlled. A threshold should accommodate understood, acceptable variation—not hide a layout change whose cause is still unknown.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Troubleshoot a mismatch in a fixed order
- Save the evidence. Record package and browser versions, executable, OS or container, launch settings, viewport, scale, capture type, and whether the image came from CI or local development.
- Verify the mode and binary. In Puppeteer, check whether the run is headful, modern headless, or headless-shell. In Playwright, verify the installed and configured browser build.
- Pin geometry. Set CSS viewport dimensions and device scale explicitly; choose Playwright screenshot scale intentionally.
- Simplify the capture. Reproduce as a viewport shot, then add the clip or full-page capture that fails.
- Wait on application state. Replace arbitrary delay or universal network-idle assumptions with a locator or app-specific ready signal; include fonts or async data when they affect layout.
- Control changing pixels. Disable animations, hide the caret, or apply narrowly targeted screenshot-only CSS to known volatile regions.
- Align the baseline environment. Use the same OS/container and browser build/settings for baseline generation and comparison before changing thresholds.
- Reduce the reproduction. If the bug remains, capture the same page in each mode with identical state and dimensions. Keep both artifacts, inspect console and network errors, and compare computed geometry for the affected element.
Without a reproduction and the relevant environment details, there is no basis to attribute an individual mismatch to a specific GPU, operating system, container, or Chrome defect.
Common symptoms and targeted fixes
| Symptom | Check first | Next step |
|---|---|---|
| Image dimensions are scaled or unexpectedly large | CSS viewport size, device scale factor, and Playwright screenshot scale | Make geometry and output scale explicit; compare output pixel size with CSS dimensions. |
| Only headful or CI output differs | Browser executable/build, mode, OS/container, and settings | Change one variable at a time and align the baseline environment. |
| Screenshot sometimes catches a loading state | Whether the capture waits for app content, required fonts, or async data | Wait for the specific visible state; do not rely on an arbitrary sleep. |
| Full-page capture clips or changes layout | Capture type, full-page/beyond-viewport behavior, and content loading during scroll | Reproduce with a viewport shot, then isolate full-page capture options. |
| Pixels vary between otherwise similar captures | Animations, caret, timestamps, rotating content, or live updates | Stabilize only known variable regions and verify that the suppression does not mask real changes. |
| Visual assertion fails despite apparently identical page | Baseline environment and whether the page reached the same state | Align host and browser configuration; tune thresholds only for known acceptable differences. |
Or skip the browser setup
If you need a screenshot through an API rather than maintaining a local browser run, ScreenshotNeo takes a URL in one GET request and returns an image or PDF. Its capture flow accepts cookie and consent banners like a visitor, then removes 60+ known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers indicating the page verdict and billing status. It also offers an MCP server with take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request parameters. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Frequently Asked Questions
Does Puppeteer default to headful Chrome?
No. Puppeteer defaults to headless; use headless: false to launch headful Chrome.
Does Playwright’s screenshot comparison wait for identical frames?
expect(page).toHaveScreenshot() waits for two consecutive screenshots to match before comparing the last image with its baseline.
Can a screenshot API replace a local visual-regression baseline?
Not automatically: the API example captures a URL, while baseline comparison still requires a consistent capture and comparison workflow appropriate to your tests.
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.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors
