Use Playwright Test’s toHaveScreenshot() assertion to compare the page or a specific element with an expected image. The assertion waits for two consecutive screenshots to match, then compares the settled capture with the stored expectation. Reliable results still depend on controlling the page state and capture environment: a stable screenshot is not automatically a correct one.
What screenshot validation checks
A visual screenshot assertion checks whether a rendered page or component still looks like its expected image. It can catch changes that a test of text, attributes, or application state may not reveal, such as a shifted layout or an unexpected visual change. It does not decide whether a difference is a defect. When an assertion fails, you need to examine the images and determine whether the change is intended.
Playwright Test provides two scopes: expect(page).toHaveScreenshot() for a page and expect(locator).toHaveScreenshot() for a particular element. Choose the scope according to the behavior the test should protect. A page-level capture can cover the full scrollable page; a locator capture narrows the check to a component.
Write a basic screenshot assertion
In a Playwright Test test file, navigate to the relevant state and assert the screenshot. This TypeScript example shows both page and locator forms; use the one that matches the intended test rather than asserting both by default.
#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
import { test, expect } from '@playwright/test';
test('profile page matches its visual expectation', async ({ page }) => {
await page.goto('https://example.com/profile');
await expect(page).toHaveScreenshot();
});
test('profile card matches its visual expectation', async ({ page }) => {
await page.goto('https://example.com/profile');
const profileCard = page.locator('[data-testid="profile-card"]');
await expect(profileCard).toHaveScreenshot();
});Replace the example URL and selector with the route and element in your application. The assertions use Playwright Test’s screenshot comparison workflow; they are not a general browser API assertion to use outside its test runner. See the PageAssertions reference for the current assertion API and options.
On the first run, the workflow may need to establish the expected image. Treat that as baseline creation, not proof that the page is correct: inspect the captured output before accepting it. The visual comparisons guide describes the expected-image workflow. Since Playwright documentation is live and may change, check the documentation for the version installed in your project when relying on a default or option.
Make the captured state repeatable
The assertion’s consecutive-capture check helps wait for a page that has stopped changing, but it cannot make unpredictable test data or an unstable environment deterministic. First define what state the test is meant to protect, then make the route, content, and capture conditions consistent across runs.
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
- Navigate to the intended state. A screenshot test should capture the particular page state under test, not whichever state happens to appear after navigation.
- Wait for relevant content. Make sure the content that matters to the assertion is present before taking the screenshot. Waiting for the screenshot to settle does not substitute for waiting for the right application state.
- Keep rendering conditions consistent. Use a consistent viewport, browser, and rendering environment when comparing against a baseline. Differences in those conditions can change what the screenshot contains.
- Decide whether the whole page or one component is the contract. Full-page screenshots are useful when the overall scrollable layout matters. Locator screenshots focus the check and can avoid coupling an isolated component test to unrelated areas of a page.
A passing comparison means the capture falls within the configured comparison rules; it does not establish that the test chose the right state, scope, or tolerance. Those decisions belong to the test author.
Free tools Windows power users keep installed
One-click scans. No signup required.
Control motion and changing regions without hiding defects
Screenshot assertions disable animations by default. They also support caret handling, masking selected locators, and applying a stylesheet during capture. Use these controls for variation that is genuinely irrelevant to the visual contract, not simply to make a failing test pass.
- Animations: The default behavior disables them for the screenshot assertion. If motion is itself what you need to validate, a static screenshot is not a substitute for a test designed to verify that behavior.
- Caret: Caret handling can prevent a blinking text cursor from becoming irrelevant image variation.
- Masks: Mask a locator when its content changes unpredictably but the changing region is outside the purpose of the test. Keep the mask narrow. A broad mask can conceal a layout or rendering regression in the covered area.
- Stylesheet: Apply a stylesheet during capture only when its effect is part of the test’s intended normalization. A stylesheet that removes or alters meaningful UI can make the comparison less useful.
These options affect what the assertion sees. Document why each non-default control exists so a later change to the test does not turn a carefully scoped exception into an invisible hole in visual coverage. Consult the PageAssertions documentation for supported option names and behavior for your installed version.
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.
Choose capture scope and pixel scale deliberately
A page screenshot and an element screenshot answer different questions. A full-page capture can expose changes in the overall scrollable layout, while an element capture keeps attention on a component. Full-page capture and screenshot scale are configurable; decide whether the comparison should use CSS pixels or device pixels, then keep that choice consistent when establishing and checking the baseline.
| Choice | Use it when | Trade-off |
|---|---|---|
| Page versus locator | The expected behavior concerns the entire page, or a specific component, respectively. | A wider capture covers more layout but can include more unrelated change; a narrower capture reduces scope but cannot catch defects outside the element. |
| CSS-pixel versus device-pixel scale | You need a particular screenshot scale and can keep it fixed across runs. | A change of scale changes the captured image and can make a baseline incomparable to an earlier one. |
| Full-page versus viewport capture | The content below the initial viewport matters, or the test is specifically about the visible viewport. | A viewport capture does not cover the rest of the scrollable page; a full-page capture makes the assertion cover more content. |
Playwright documents page capture and related screenshot options in its Page reference. Keep the browser, viewport, and scale consistent for the baseline and subsequent comparisons. Otherwise, investigate the capture setup before interpreting a difference as an application regression.
Set comparison tolerance with intent
Playwright exposes separate controls for pixel color sensitivity and for the amount of the image allowed to differ. The documented default threshold is 0.2; it controls acceptable perceived color difference between corresponding pixels in YIQ color space. maxDiffPixels and maxDiffPixelRatio instead limit the permitted number or proportion of differing pixels. Check the TestProject reference and the assertion reference for the option details applicable to your installed version.
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
- Use
thresholdwhen the question is how much corresponding pixel colors may differ. - Use
maxDiffPixelswhen the test should set an absolute limit on the count of differing pixels. - Use
maxDiffPixelRatiowhen the intended limit is a proportion of the image.
These are not interchangeable settings. Raising color tolerance does not mean the same thing as permitting more changed pixels. There is no universally correct tolerance prescribed by the documentation: choose one that reflects the test’s purpose, then inspect the diff when it fails. A permissive setting can reduce noise, but it can also allow meaningful visual changes through.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Review a failure before updating the baseline
When a screenshot assertion fails, inspect the expected image, actual image, and diff image. Ask whether the rendered change is intentional and whether it affects the behavior the test is meant to protect. If it is a regression, fix the application or stabilize the test setup; do not update the baseline just to clear the failure. Update an expected image only after reviewing and accepting the visual change.
- Open the expected, actual, and diff images produced by the visual comparison workflow.
- Identify where the images differ and whether the difference comes from the application, page state, or capture conditions.
- Decide whether the change is an intended design update or an unwanted regression.
- If the change is intended, review its effects and then update the expected image using the Playwright Test snapshot workflow for your installed version.
- Run the test again to confirm that the accepted expectation now represents the intended state.
Blindly refreshing snapshots can turn a visual defect into the new expectation. The Playwright visual comparisons guide explains the expected-image workflow; follow the commands and update behavior documented for the version your project uses.
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 common screenshot failures
| Symptom | Likely cause | What to do |
|---|---|---|
| The assertion fails repeatedly with small or shifting differences. | The page state or rendering conditions are not consistent across runs. | Stabilize test data and state, wait for relevant content, and keep browser, viewport, and scale consistent. Use a mask only for a truly irrelevant changing region. |
| A large part of the page differs. | The application may have changed, or the assertion may be capturing a different state, scope, or environment. | Compare expected, actual, and diff images. Verify the route, relevant content, screenshot scope, and rendering setup before adjusting tolerance. |
| A tiny color change fails even though the layout is unchanged. | The color-difference threshold may be too strict for the test’s intended sensitivity. | Check the documented threshold behavior and decide whether the color variation is meaningful. Adjust only with a reason; inspect the resulting diff rather than using tolerance as a blanket fix. |
| The test passes despite a change you expected it to catch. | The permitted differences may be too generous, or masking/styles may hide the relevant area. | Review threshold and difference limits, then narrow masks or capture styles so the assertion observes the behavior under test. |
| A component test breaks after an unrelated page change. | The assertion may be using page scope even though the intended contract is component-level. | Consider a locator screenshot for the relevant component, while retaining a page-level check where overall layout is part of the test contract. |
| The baseline differs after changing browser or screenshot scale. | The new environment or scale produces a different capture. | Restore consistent capture conditions, or deliberately review and establish a baseline for the changed conditions. Do not treat old and new images as directly equivalent without review. |
Or skip the browser setup
If your goal is to capture a website image rather than validate your own UI against a Playwright baseline, ScreenshotNeo offers a screenshot API and MCP server. Its GET endpoint returns an image or PDF for a URL. For example, this cURL request saves a WebP screenshot:
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 request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Frequently Asked Questions
Can I use Playwright screenshot assertions without Playwright Test?
The documented screenshot assertions are part of Playwright Test’s test-runner workflow; they are not presented as general-purpose assertions for use outside that runner.
Does a passing screenshot assertion prove the page is correct?
No. It means the capture met the configured image-comparison rules. You still need to choose a meaningful state and scope, and review unexpected visual 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.
