Use Playwright Test’s toHaveScreenshot() assertion to capture a page or a specific element, compare it with a saved baseline, and review any visual difference before accepting a new baseline. The first run creates the reference image; later runs compare against it. Reliable results depend on controlling the page state and running baseline creation and comparison in a consistent environment.
What Playwright screenshot assertions do
Playwright Test includes visual screenshot assertions for its test runner: expect(page).toHaveScreenshot() checks a page, while expect(locator).toHaveScreenshot() checks the element matched by a locator. The assertion captures an image and compares it with an expected snapshot associated with the test. That makes it useful for catching unintended layout, styling, or content changes that ordinary functional assertions may not detect.
A screenshot assertion is not a guarantee that a page looks identical on every machine. Playwright’s “Visual comparisons” documentation warns that browser rendering can vary with the host operating system, browser version and settings, hardware, power source, headless mode, and other factors. The practical goal is repeatable comparison in a controlled environment, not universal pixel identity.
Add a page or element snapshot assertion
Capture a whole page
In a Playwright Test file, navigate to the state you want to protect and assert against a named screenshot:
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 →#1 Best Overall
- Grafco Ishihara Test Chart Book
- Package Info: Each
- Includes four special plates for tests to determine the kind and degree of defect in color vision.
- Image may not reflect actual product sold. Please read description carefully.
- GHF1254
import { test, expect } from '@playwright/test';
test('landing page visual state', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('landing.png');
});The test assumes your project’s Playwright Test configuration can resolve / to the application under test. Ensure the application is running and that the route renders the intended state before the assertion.
Capture one element
When the contract is a particular component rather than the entire composition, assert on a locator:
await expect(page.getByRole('button', { name: 'Continue' }))
.toHaveScreenshot('continue-button.png');Prefer a stable, accessible locator. A page-level snapshot can reveal changed spacing or interactions among sections, but it also includes more content that may vary. A locator snapshot narrows the comparison to the component whose appearance matters.
Create and maintain baselines deliberately
First run
On the first execution, no expected image exists. Playwright reports the missing snapshot and writes the actual image as the initial reference. Review that image rather than treating file creation as approval: a baseline can faithfully capture an incorrect state if the test navigated to the wrong route, rendered incomplete data, or captured too early.
Rank #2
- individuals with color vision defect should see a different figure from individuals with normal color vision.
- Makes use of the peculiarity that in red-green blindness, blue and yellow appear remarkably bright compared with red and green
- Diagnostic plates: intended to determine the type of color vision defect
- Ishihara Test Chart Books for Color Deficiency 24 Plates with usar manual
Commit the reviewed snapshot directory with the test. Keeping expected images in version control makes the visual contract reviewable alongside the code that defines it.
Later runs
On subsequent executions, Playwright captures a new image and compares it with the committed expected image. If the images differ beyond the configured tolerance, the assertion fails and the generated diff should help identify the changed region.
Accept an intentional visual change
- Run the affected test and inspect the actual image and diff.
- Decide whether the changed appearance is intended by reviewing the relevant application change and state.
- Only when it is intentional, run
npx playwright test --update-snapshots. - Inspect the updated image files, then commit the test and intended baseline changes together.
Updating snapshots replaces the expected reference; it does not establish that the new interface is correct. If a broad update changes many unrelated snapshots, investigate the environment or app state before accepting the batch.
Make screenshot captures repeatable
Keep the rendering environment consistent
Generate and compare baselines using the same operating system, browser version, browser settings, hardware class, and headless configuration where possible. A baseline created on one setup may differ on another even when the application code has not changed. Pinning the project’s browser version and using the same CI environment for updates and routine checks can reduce this source of noise.
PC 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 & 11Crashes, 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 minuteRank #3
- Vanishing design: Only people with good color vision can see the sign. If you are colorblind you won’t see anything.
- Transformation design: Color blind people will see a different sign than people with no color vision handicap.
- Hidden digit design: Only colorblind people are able to spot the sign. If you have perfect color vision, you won’t be able to see it.
- Classification design: This is used to differentiate between red- and green-blind persons. The vanishing design is used on either side of the plate, one side for deutan defects an the other for protans.
Playwright’s official “Visual comparisons” guide specifically notes variation from the host OS, browser version, settings, hardware, battery versus power-adapter use, and headless mode. Treat environment changes as a possible cause of diffs rather than immediately changing the expected images.
Stabilize application state
- Use deterministic test data and wait for the page state that the screenshot is meant to represent.
- Keep time-sensitive or randomly generated content stable where it is not the subject of the test.
- Avoid capturing during transitions or while data is still loading.
- Move the pointer away from interactive content, or to an inert area, if an accidental hover state would alter the image.
- Use descriptive snapshot names that identify the route or component and state under test.
Playwright waits for two consecutive screenshots to match before making its comparison. That settling behavior helps with transient rendering, but it cannot make different machines render alike or correct nondeterministic application state.
Control noise without hiding regressions
Screenshot options include animation behavior, caret behavior, scale, clipping, and stylesheets. Project configuration also provides a color threshold and limits for differing pixels. Use these controls to address known, understood sources of volatility—not to make failures disappear.
Animations, carets, and capture scope
Where motion is irrelevant to the visual contract, configure the screenshot to disable animations. Caret behavior can also be controlled for captures of text inputs. Use clipping or a locator screenshot to constrain the captured region when a full-page image would include unrelated, volatile content. Check the installed Playwright version’s documentation for the precise option names and behavior available to your project.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #4
- This illustrated & interactive study guide for the National Counselor Exam (NCE) uses images, colors, mnemonics, and humor to engage brains in effective study.
- 150+ page activity book including coloring book pages, fill in the blank sheets, and tear-out flashcards with content addressing all domains covered in the NCE + CPCE counselor exams.
- Full size 8.5x11, spiral-bound for lie-flat studying.
- Printed on premium, 80lb textured paper you can color and highlight with no bleed.
- Drawn by (human!) hand. Printed and bound in the USA.
Stylesheets for genuinely volatile areas
A screenshot stylesheet can hide or neutralize content known to change independently of the interface being tested, such as a volatile embedded region. Apply this narrowly: masking a timestamp may be reasonable when timestamp appearance is not under test, while hiding a navigation area or price can conceal a real regression. Keep the stylesheet easy for reviewers to inspect.
Thresholds and differing-pixel limits
The Playwright Test configuration reference gives Pixelmatch’s color threshold a default of 0.2, on a scale from 0 (strict) to 1 (lax). Maximum differing-pixel counts or ratios can also be configured; they are unset by default. A higher color threshold or larger allowed pixel difference can reduce failures from small rendering variation, but can also let meaningful visual changes pass. Tune against representative diffs and retain a human review path for changes that matter.
Diagnose a visual diff before updating
When an assertion fails, first establish whether the image represents a real product change. Review the actual image and diff together with the test and application changes. Then check these likely causes:
- Intentional UI change: Confirm that the new spacing, typography, color, or content is expected before updating the baseline.
- Unstable state or data: Verify that the app reached the intended state and that test data did not change unexpectedly.
- Environment drift: Check whether the operating system, browser version, browser settings, hardware, power conditions, or headless configuration changed.
- Transient visual state: Look for an animation, hover effect, blinking caret, or dynamic region included in the capture.
- Wrong capture scope: Confirm that the test is capturing the intended page or locator and not an accidental state or unrelated content.
After diagnosing the cause, fix the test or environment when the difference is noise. Update the reference only when the new appearance is the desired result.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteWhen built-in snapshots are enough—and when a hosted workflow may help
For a team already using Playwright Test, its built-in screenshot assertion is the direct starting point: snapshots live with the test workflow and can be reviewed as image changes in code review. Hosted products such as Percy and Chromatic document Playwright workflows; their hosted review or broader cross-browser workflows may suit teams with different collaboration needs. Choose based on review process, coverage requirements, CI fit, data handling, usage limits, and current terms. Available documentation does not establish a complete, independently verified comparison of current prices or terms for those services.
Or skip the browser setup
ScreenshotNeo is a screenshot API and MCP server, not a Playwright Test baseline assertion system. It can be useful when you need a clean capture through a single request rather than setting up a browser capture flow; you can still use Playwright Test for your repository’s baseline comparisons.
For example, this cURL request captures a page as WebP (see the ScreenshotNeo API documentation for options):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. 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 with no card; paid plans start at $5 for 3,000 shots.
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 →Sign up for ScreenshotNeo’s free plan and get 1,000 screenshots a month with no card.
Frequently Asked Questions
Can I use Playwright screenshot assertions without Playwright Test?
The documented toHaveScreenshot() page and locator assertions are features of the Playwright Test runner.
Do screenshot snapshots prove that a page is accessible or functionally correct?
No. They compare rendered appearance; keep functional and accessibility checks for behavior and semantics.
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.
