Use Playwright Test’s expect(page).toHaveScreenshot() (or the locator equivalent) to capture a baseline image, compare later renders with it, and review intentional changes with --update-snapshots. Reliable results require pinned browser and operating-system versions, deterministic page data, controlled animations, and narrowly chosen diff tolerances.
What Playwright screenshot testing does
Playwright Test provides visual regression assertions that compare a newly rendered image with a reference file committed alongside your tests. A page assertion covers the page composition; a locator assertion limits the contract to one component or region.
- Page scope: use
toHaveScreenshot()when the whole page layout is the subject. - Locator scope: use
locator.toHaveScreenshot()for headers, cards, dialogs, or other components so unrelated page changes do not create noise. - Baseline behavior: the first run creates the reference image. Later runs compare against it and report expected, actual, and diff images when they differ.
Screenshot assertions wait for two consecutive screenshots to be identical before comparing them. That extra stabilization reduces capture-time movement, but it cannot make changing application data deterministic.
Set up a visual test
Install and create a test
- Install Playwright Test in your project and install the browser binaries.
- Create a test file such as
tests/visual.spec.ts. - Navigate to a stable URL, then assert the page or a locator.
import { test, expect } from '@playwright/test';
test('landing page visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('landing-page.png');
});
test('header visual baseline', async ({ page }) => {
await page.goto('https://example.com');
await expect(page.getByRole('banner')).toHaveScreenshot('header.png');
});Run the test with npx playwright test. On the first execution Playwright reports that the snapshot is missing and writes the actual image as the reference. Commit the generated snapshot directory with the test code.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Choose a useful viewport and project
Define the browser, viewport, color scheme, locale, and other settings in your Playwright project configuration. A baseline is only meaningful when comparison runs use the same rendering inputs. Keep the project configuration under version control so local and CI runs do not silently diverge.
Manage the baseline lifecycle
Reviewing an ordinary failure
- Open the expected, actual, and diff images produced by the failed assertion.
- Decide whether the difference is an intended UI change, a test-data problem, or rendering instability.
- If it is a defect, fix the application or test and rerun.
- If it is intentional, update the reference only after reviewing the image.
Updating intentional changes
Promote reviewed changes with:
npx playwright test --update-snapshotsThis replaces references, so run it deliberately and inspect the resulting files before committing them. Do not use snapshot updates as a way to make an unexplained failure green.
Organize and review snapshots
Keep snapshots in the directory Playwright creates for the test and commit them to version control. Review image changes in the same pull request as the UI or test change. A missing or unexpectedly regenerated directory is a useful signal that a project name, browser, or snapshot path changed.
Make captures deterministic
Pin the rendering environment
Playwright identifies operating-system version, browser version, browser settings, hardware, power source, and headless mode as possible rendering influences. Use the same operating-system and browser versions for baseline generation and CI comparison. A practical approach is to generate and verify snapshots in the same pinned CI image rather than accepting developer-machine baselines.
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 reinstallControl animations
Screenshot assertions disable CSS animations and Web Animations by default. Finite animations are fast-forwarded and infinite animations are canceled for the capture. Leave that default in place unless the test specifically verifies an animation frame. Enabling animations makes timing and frame selection part of the visual contract.
Remove hover and focus surprises
Move the mouse away from interactive elements before capture when hover styling is not the subject. Also establish the intended focus state explicitly; a focused button or input can legitimately alter borders, shadows, and layout.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Mask dynamic regions
Mask timestamps, rotating promotions, avatars, advertisements, user-specific names, and other regions that are not part of the assertion. The page assertion API accepts locators to mask, allowing the test to preserve layout while hiding changing pixels. Prefer deterministic fixtures and stable network responses as well; masking should not conceal a UI contract you actually need to test.
Wait for meaningful readiness
Navigate, establish the test data, and wait for the element or state that proves the page is ready. A screenshot taken while fonts, images, or client-side data are still arriving can produce a legitimate but useless diff. The built-in consecutive-identical-screenshot wait helps with settling, but it does not replace an application-level readiness condition.
Set comparison strictness deliberately
Use the least tolerance that accommodates known rendering noise. Playwright exposes three independent controls:
| Option | What it permits | When to use it |
|---|---|---|
threshold |
Per-pixel perceived color difference. | Small anti-aliasing or color-rendering variation. |
maxDiffPixels |
An absolute maximum number of differing pixels. | A fixed, reviewable allowance for a known small artifact. |
maxDiffPixelRatio |
A maximum proportion of differing pixels. | A size-independent allowance across similarly structured images. |
Project-level defaults can be set under expect.toHaveScreenshot. Pixelmatch’s documented default threshold is 0.2. The default assertion expect timeout documented in project configuration is 5,000 ms. Treat any increase as a reviewed policy change: a larger allowance can hide a real regression. Prefer a locator-scoped assertion or a mask before raising global tolerances.
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
threshold: 0.2,
maxDiffPixels: 40,
maxDiffPixelRatio: 0.001,
},
},
});Keep per-test overrides close to the assertion when only one component needs a special rule, and document why the exception exists.
Run visual tests in CI
Use a pinned project
Generate baselines and compare them in the same operating-system and browser environment. Pin browser versions and the CI image, and avoid mixing headed local captures with headless CI references unless you have verified that the rendering is equivalent.
Recommended Free Tools
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Store artifacts on failure
Retain expected, actual, and diff images for failed jobs. They answer whether the change is geometric, color-related, missing content, or a transient state.
Diagnose with Trace Viewer
When an image alone does not explain a failure, open the Playwright trace. Trace Viewer provides a test timeline and DOM snapshots, letting you see navigation, actions, waits, and page state around the capture. Tracing every test is performance-heavy; configure it for retries or targeted runs rather than enabling it unconditionally for an entire suite.
Separate code and baseline review
Require reviewers to inspect snapshot diffs in the same change that modifies UI code. A pull request that changes only a baseline without an explanatory application or test change deserves investigation.
Choose page-wide or component coverage
| Question | Page assertion | Locator assertion |
|---|---|---|
| What is the contract? | Overall composition, routing shell, or a complete screen. | A specific component or region. |
| How much unrelated noise? | More: navigation, ads, and dynamic areas can affect the image. | Less: only the selected element is compared. |
| Best use | Smoke-level visual coverage of important screens. | Focused regression tests for reusable UI components. |
Use both where appropriate: a small set of page contracts catches composition errors, while locator tests provide precise failures for components.
Common failures and fixes
“Snapshot doesn’t exist” on every run
Cause: the test is running in a different project, browser, path, or working directory than the one that generated the reference. Fix: verify the project name, snapshot directory, test file location, and checked-in files; generate once in the intended pinned environment.
Large diffs after a browser or OS update
Cause: font rasterization, subpixel layout, and browser rendering changed. Fix: restore the pinned environment or intentionally regenerate all affected references after reviewing the complete diff.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Only timestamps, ads, or rotating content differ
Cause: nondeterministic data. Fix: use fixed fixtures or mocked responses, then mask regions that are outside the visual contract.
Diffs show hover, focus, or animation frames
Cause: pointer state, focus state, or explicitly enabled animation. Fix: move the pointer away, set focus intentionally, and keep the default animation disabling unless animation timing is what you are testing.
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 glitchesTimeout while waiting for the screenshot
Cause: the page or locator never reaches a stable, visible state within the assertion timeout. Fix: wait for a meaningful readiness signal, ensure the locator resolves to the intended element, inspect the trace, and only then consider a narrowly scoped timeout increase.
CI failures are hard to reproduce
Cause: environment or network differences. Fix: pin the OS and browser, use deterministic data and stable network state, preserve diff artifacts, and collect traces on retries.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need an image or PDF from a URL rather than an in-repository Playwright assertion, ScreenshotNeo provides a single HTTP endpoint. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
Use the documented options for full-page or element capture, device and viewport settings, retina scale, dark mode, custom CSS or JavaScript, clicks, selector waits, network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, and usage reporting. Those controls complement Playwright tests; they do not replace committed, reviewable baselines.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);See the ScreenshotNeo documentation for request options. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots, and every feature is available on every plan. Create a free ScreenshotNeo account to try it.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
FAQ
Should I use toMatchSnapshot() for screenshots?
Playwright documents that workflow, but its snapshot-assertions reference recommends toHaveScreenshot() for screenshot comparisons. Use toMatchSnapshot() for non-image values or a deliberate lower-level workflow.
Can visual tests prove accessibility or functional correctness?
No. A matching image cannot verify keyboard behavior, semantics, network responses, or business logic. Pair screenshot assertions with functional and accessibility tests.
How often should baselines be regenerated?
Only when a reviewed UI or rendering-environment change is intentional. Regenerating on a schedule without reviewing the images removes the regression signal.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Frequently Asked Questions
What does a Playwright visual diff contain?
A failed screenshot assertion provides the expected reference, the newly captured actual image, and a diff image so you can identify the changed region.
Is a locator screenshot faster than a full-page screenshot?
It usually captures and compares fewer pixels, and it reduces unrelated failures; actual runtime still depends on page loading and test setup.
Where should snapshot files live?
Keep the directory generated by Playwright beside the test project and commit it to version control so reviewers can inspect changes.
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.
