How do I add visual comparison testing to a Playwright test? Use Playwright Test’s toHaveScreenshot() assertion: capture a page or locator, review and commit the first-run reference image, then let later test runs compare fresh screenshots against it. Keep the rendering environment consistent, control dynamic page content, and inspect diffs before changing tolerances or updating baselines.
What Playwright visual tests compare
Playwright Test supports screenshot assertions for both a full page and a focused locator. The APIs are part of the Playwright test runner; the documented comparison workflow is described in Playwright’s Visual comparisons guide and the PageAssertions API.
On an initial run, when the expected screenshot does not exist, Playwright creates it. On subsequent runs it captures the page again and compares that image with the expected one. The reference image is a test artifact that should be inspected and committed with the test—not accepted as correct merely because it was generated.
For page assertions, Playwright waits for two consecutive screenshots to match before comparing. This helps screenshots settle, but it cannot make application data deterministic or guarantee identical rendering across different machines.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →#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.
Add a screenshot assertion
Use the same setup and navigation your UI test needs, then assert on either the page or the component the test owns. This example assumes Playwright Test is already installed and configured in the project:
import { test, expect } from '@playwright/test';
test('checkout page matches its reference', async ({ page }) => {
await page.goto('http://localhost:3000/checkout');
await expect(page).toHaveScreenshot('checkout-page.png');
});
test('cart summary matches its reference', async ({ page }) => {
await page.goto('http://localhost:3000/checkout');
const summary = page.locator('[data-testid="cart-summary"]');
await expect(summary).toHaveScreenshot('cart-summary.png');
});A locator assertion is useful when the test is responsible for a component rather than the entire page composition. A page assertion covers the page screenshot, so it can catch unintended changes outside one component as well. Give screenshots a descriptive name when it makes the expected image easier to identify.
- Run the test once to generate the expected image.
- Open and inspect the generated image in the test’s snapshot output. Confirm that the app reached the intended state and that the image is a valid reference.
- Commit the reference image alongside the test.
- Run the test again. A later screenshot is compared with the committed expected image.
Snapshot file organization and naming conventions can depend on the test and project configuration. Check the behavior for the Playwright version installed in your project in the Visual comparisons documentation.
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.
Make screenshots deterministic
First reduce sources of variation in the app and test; only then decide whether a comparison tolerance is needed. Playwright’s Visual comparisons page notes: “Browser rendering can vary based on the host OS, version, settings, hardware, power source (battery vs. power adapter), headless mode, and other factors.” Run baseline creation and comparisons in a consistent environment—ideally the same browser version, operating system, and rendering setup used by the project’s CI.
Stabilize the page state
- Use predictable test data and drive the page to a known state before taking the screenshot.
- Wait for the UI condition that matters to the test. The screenshot assertion’s settling behavior does not substitute for waiting for application-specific content or transitions to finish.
- Where appropriate, use the documented screenshot options to wait for a selector, apply a delay, or otherwise control capture timing. See the PageAssertions API for the options supported by your installed version.
- For genuinely volatile regions, consider masking the changing content or applying a screenshot-specific stylesheet filter. Use these narrowly: hiding a region can also hide a real regression in it. The Visual comparisons guide covers stylesheet-based filtering.
Keep the rendering environment consistent
Differences in host OS, browser version, settings, hardware, power source, or headless mode can change pixels even when the UI code has not changed. If the goal is reliable regression detection, generate and compare baselines in the same controlled environment. If the goal also includes cross-browser or cross-OS coverage, treat those environments as separate comparison targets with their own references rather than assuming one image should match everywhere.
Choose screenshot scope and comparison strictness
Full page or component
Use page.toHaveScreenshot() when the test owns the page composition or when layout changes anywhere on the page matter. Use locator.toHaveScreenshot() when the intended contract is a specific component and unrelated page changes should not fail that assertion. Neither scope is universally better; choose the scope that matches what the test is meant to protect.
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.
Strict or tolerant comparison
Start with strict comparison settings. If a failure reveals a small, understood rendering difference that is acceptable for the project, tune only after reviewing the actual diff. Playwright provides maxDiffPixels, maxDiffPixelRatio, and a color threshold for screenshot comparisons. A looser setting can reduce failures from insignificant variation, but can also allow a meaningful change to pass unnoticed.
Options can be set on an individual assertion or through test configuration where shared expectations are appropriate. Consult the version-matched SnapshotAssertions API and TestConfig API; option availability and defaults should be checked against the Playwright version actually installed.
Windows 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 reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteOne environment or a matrix
For stable visual regression detection, use a consistent environment. For cross-browser or cross-platform coverage, run the relevant projects separately and maintain comparisons appropriate to each rendering environment. A matrix answers a broader compatibility question, but it also means more references to review and maintain.
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
Review and update baselines safely
When a UI change is intentional, regenerate snapshots with Playwright’s documented update workflow:
npx playwright test --update-snapshotsReview every changed expected image before committing it, and commit baseline updates with the UI change they represent. Do not use the update flag simply to make a failing test green: an unexpected change may be the regression the test was designed to catch. Refer to the Visual comparisons guide for the documented baseline workflow.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot visual test failures
The first run created a screenshot, but the test still needs review
The initial image is a proposed reference, not an independent check that the UI is correct. Open it, verify the page state and visible content, then commit it only if it represents the intended result.
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 →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.
The same test differs across machines
Compare the browser version, OS, rendering settings, hardware, power source, and headless mode used to create and check the baseline. Align the environments before widening tolerances; the official guide identifies these as factors that can affect rendering.
A page assertion captures changing content
Check whether test data, asynchronous content, animation, or a dynamic region changes between captures. Make the test state deterministic, wait for the relevant UI condition, or narrowly mask/filter content that is genuinely outside the assertion’s purpose. The consecutive-screenshot wait helps with settling but does not eliminate application-specific dynamics.
A small diff fails the test
Inspect the expected, actual, and diff images first. Decide whether the changed pixels represent an unwanted UI regression or an acceptable rendering difference. If a measured difference is acceptable, adjust maxDiffPixels, maxDiffPixelRatio, or threshold narrowly and verify that the test still catches the smallest change that matters to the team.
You cannot tell what happened before the mismatch
Use Playwright Trace Viewer to inspect the page state and actions around the failure, along with screenshot artifacts where available. See the Trace viewer documentation for its inspection workflow.
Or skip the browser setup
If you need screenshots as an API output rather than repository-managed Playwright baselines, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. For example, capture a page as WebP with cURL:
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 API documentation for request options. ScreenshotNeo accepts cookie or 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 responses report the page verdict and billing status in headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents and MCP clients. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up free for 1,000 screenshots a month—no card required.
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.
