Use await expect(page).toHaveScreenshot() for Playwright image comparisons. Playwright Test captures a reference image on the first run, then waits for two consecutive identical screenshots before comparing future runs. That settling step, plus deterministic test data and a disciplined baseline-review process, is what makes visual regression testing useful rather than flaky.
What Playwright snapshot comparison does
Playwright’s visual workflow stores a “golden” screenshot and compares later screenshots with it. Screenshot assertions are available in the Playwright Test runner, not in an arbitrary script using only the browser library. The main assertion is toHaveScreenshot(), which Microsoft documents for visual comparison.
Use a page assertion when the whole rendered page is the subject of the test. Use a locator assertion when you want one component, panel, or region. Locator scope prevents unrelated navigation, ads, or surrounding layout from causing failures.
Page versus locator
import { test, expect } from '@playwright/test';
test('checkout summary is visually stable', async ({ page }) => {
await page.goto('/checkout');
await expect(page.getByTestId('summary')).toHaveScreenshot('checkout-summary.png');
});For component tests, capture the mounted component’s root locator. A root-level assertion keeps the snapshot about the component instead of the test page that hosts it.
#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
toHaveScreenshot versus toMatchSnapshot
page.toHaveScreenshot() and locator.toHaveScreenshot() are purpose-built image assertions. They support named PNG snapshots and lossless WebP names. expect(value).toMatchSnapshot() compares text or arbitrary binary data and is still appropriate for non-image snapshots; its screenshot overload is documented, but Playwright recommends toHaveScreenshot() for screenshots. Page and locator screenshot assertions were added in Playwright 1.23; the generic screenshot overload is documented from 1.22.
Creating, storing, and updating baselines
- Run the test without an existing golden image. Playwright writes the reference image in a test-file-specific snapshot directory.
- Commit that snapshot directory to version control. Review image changes alongside the code that caused them.
- Run the same test in subsequent builds. A mismatch produces expected, actual, and diff images.
- When a UI change is intentional, run
npx playwright test --update-snapshots, inspect the new images, and commit them. Never use the flag to conceal an unexplained regression.
Snapshot names include the browser and platform/project because rendering differs across operating systems and browsers. You can customize locations with snapshotPathTemplate; when passing path segments, keep them inside the test file’s snapshot directory.
Make screenshots deterministic
Playwright warns that host OS, browser version, browser settings, hardware, power source, and headless mode can change pixels. Generate and consume baselines in one pinned environment. A practical harness controls:
- Browser and operating-system image, including the exact browser version.
- Viewport, device scale factor, and device preset.
- Fonts and font-loading completion.
- Locale, timezone, and test data.
- Network responses, feature flags, and third-party resources.
Screenshot assertions disable CSS animations, CSS transitions, and Web Animations by default. You can still have unstable content from clocks, avatars, rotating ads, cursors, random IDs, or delayed data.
Mask volatile content
Mask timestamps, user avatars, ads, cursors, and other regions that are not part of the visual contract. The default mask overlay is pink, and it can be customized. Hide or neutralize dynamic areas with a screenshot style or stylePath stylesheet; Playwright supports content in shadow DOM and, where supported by the API, frames.
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
Control hover and settling
Move the pointer away from accidental hover targets when hover styling is not under test. The assertion itself waits for two consecutive identical screenshots, but it cannot make a changing clock or live feed deterministic. Freeze such data, stub the response, mask the region, or apply a screenshot stylesheet.
import { test, expect } from '@playwright/test';
test('home page visual baseline', async ({ page }) => {
await page.goto('/');
await page.mouse.move(-1, -1);
await expect(page).toHaveScreenshot('home.png', {
fullPage: true,
animations: 'disabled',
mask: [page.getByTestId('last-updated')],
maxDiffPixels: 100,
});
});maxDiffPixels: 100 is only an example. Choose a value after reviewing your own rendering noise; Playwright does not prescribe a universal number.
Diff controls: what each option means
| Option | Meaning | Use it when |
|---|---|---|
maxDiffPixels |
Absolute number of changed pixels allowed. | A small, known amount of raster noise is acceptable. |
maxDiffPixelRatio |
Allowed changed-pixel ratio from 0 to 1. | Images have different dimensions or you need a proportional limit. |
threshold |
Per-pixel perceived color difference; pixelmatch’s YIQ-based value ranges from 0 (strict) to 1 (lax), with a documented default of 0.2. | Minor color-rendering differences are understood and documented. |
Start strict. Relax only after identifying known rendering noise. A threshold is not a substitute for fixing a wrong font, viewport, browser, or data fixture.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsHow to interpret a failure
- Large coherent region: inspect the CSS, layout, content, and product requirement. This is often a real change.
- Text-edge differences or speckled noise across the page: verify fonts, browser and OS versions, device scale, and image decoding.
- A moving or time-dependent region: freeze its data, mask it, or apply a screenshot stylesheet.
- Only hover styling differs: move the pointer or explicitly test the hover state.
- A component image contains unrelated page UI: assert against the component’s root locator.
Playwright UI Mode provides expected, actual, and diff images for interactive diagnosis. Use the diff to decide whether to fix the test environment, change the product, or intentionally update the baseline.
A maintainable review and update workflow
Keep the comparison contract narrow
Give each test one visual purpose: a checkout summary, a dialog, or a complete route. Name snapshots clearly and use locator scope for components. Full-page images are useful for page-level layout, but they also include more content that can legitimately change.
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.
Pin the producer and consumer
Do not generate baselines on a laptop and consume them on a different operating system if pixel-level stability matters. Build the images in the same pinned CI container or runner used for comparison. Keep browser updates deliberate: a browser upgrade can require a reviewed baseline migration.
Review updates as code
An intentional design change should include its visual diff and the corresponding implementation or requirement. If a snapshot changes without an explanation, stop and investigate rather than passing --update-snapshots.
Common failures and fixes
“Snapshot does not exist”
This is normal on a first run or when a project/browser combination is new. Run the test once to create the baseline, then commit the generated snapshot directory.
Failures only in CI
Compare OS, browser version, fonts, viewport, device scale, locale, timezone, headless mode, and test data. Pin the environment and ensure web fonts and images have loaded before the assertion.
Every run differs slightly
Look for animations, transitions, timers, random content, network responses, ads, avatars, and hover state. Disable animations, stub data, mask volatile locators, move the pointer, or use stylePath.
Rank #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
The whole page fails after a small component change
Narrow the assertion to a locator, or keep the full-page test and add a separate component-level test. The correct scope depends on whether surrounding layout is part of the contract.
Recommended Free Tools
Updating the snapshot hides a bug
Restore the baseline and inspect expected, actual, and diff images. Confirm the product requirement and code review before updating. The update command is a change-management tool, not a repair command.
Colors differ but geometry is correct
Check color profiles, browser/OS rendering, fonts, and image decoding first. If the remaining variation is understood, adjust threshold or a pixel limit narrowly and document why.
Or skip the browser setup
If you need a clean image of a URL rather than an assertion inside a Playwright test, ScreenshotNeo is a direct alternative. Its GET API accepts a URL and returns PNG, JPEG, WebP, or PDF. Before capture it accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and whether it was billed.
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 full option set. It supports full-page lazy-image capture, CSS-selector elements, dark mode, 12 device presets and custom viewports, retina scale, PDF paper settings and page ranges, HTML/CSS rendering, custom JavaScript and CSS, clicks, selector/delay/network-idle waits, request and resource blocking, headers, cookies, user agents, Authorization, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API, and an OpenAPI specification. Common screenshot-API parameter names also work, easing migration.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →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}`);ScreenshotNeo also has an MCP server with take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Every feature is on every plan: 1,000 shots/month free without a card; Starter $5 for 3,000; Growth $15 for 15,000; Pro $39 for 60,000; Scale $99 for 250,000; and Business $249 for 1,000,000. Yearly billing gives two months free.
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.
Start with 1,000 free screenshots a month—no card required.
Practical decision guide
- Choose
toHaveScreenshot()when a visual assertion belongs in a Playwright Test suite and should fail a build when pixels change. - Choose a locator assertion for a component or bounded region.
- Use
toMatchSnapshot()for text or arbitrary binary snapshots rather than ordinary screenshot comparisons. - Use strict limits and deterministic fixtures before changing thresholds.
- Use ScreenshotNeo when you need an external URL capture, PDF, cleanup of consent UI, an API workflow, or an MCP tool rather than browser-test infrastructure.
Frequently Asked Questions
Can I compare screenshots with Playwright library code without Playwright Test?
The documented screenshot assertions are part of the Playwright Test runner. A standalone browser script can capture images, but the built-in visual assertion workflow requires the test runner.
Should visual baselines be shared across browsers?
Usually no. Snapshot names include browser and platform/project because rendering differs. Generate and compare each baseline in its pinned target environment.
Free tools Windows power users keep installed
One-click scans. No signup required.
What file formats can screenshot assertions use?
Named PNG snapshots are supported, as are lossless WebP names. Use the format that fits your repository and review workflow.
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.
