Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use Playwright Test’s toHaveScreenshot() assertion to compare a page or locator against a saved reference image. The first run creates the baseline; later runs compare new screenshots against it. For dependable results, stabilize the page and run baselines and comparisons in a consistent environment before adjusting tolerance values.
How Playwright image comparison works
Playwright’s visual assertion is part of the Playwright Test runner. It captures a screenshot, compares it with a reference snapshot, and fails the test when the difference exceeds the configured limits. On the first run, no reference exists, so Playwright creates one. Treat that image as a proposed baseline: inspect it, then commit it with the test if it represents the intended UI.
Screenshot assertions wait for two consecutive screenshots to produce the same result before using the last capture for comparison. This helps settle transient rendering, but it does not make nondeterministic content safe: animated data, rotating banners, live clocks, and layout shifts may still make tests unreliable.
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 →Compare a whole page
In a test file, use await expect(page).toHaveScreenshot(). The default reference format is PNG. Playwright also supports lossless WebP when you use a .webp snapshot name or configure that format.
import { test, expect } from '@playwright/test';
test('home page matches its reference', async ({ page }) => {
await page.goto('https://example.com');
await expect(page).toHaveScreenshot('home.png');
});Replace the example URL with a page your test environment can access. Run the test once to generate the image, review it, and add the expected snapshot to version control. Subsequent runs compare against that committed image.
#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
Compare only the component that matters
A whole-page screenshot can fail because of unrelated content. Use the locator assertion to capture a focused region, such as a navigation bar, card, or dialog:
test('product card matches its reference', async ({ page }) => {
await page.goto('https://example.com/products');
const card = page.locator('[data-testid="product-card"]');
await expect(card).toHaveScreenshot('product-card.png');
});Scoping the screenshot reduces irrelevant changes and makes the diff easier to diagnose. Prefer a stable selector, such as a test ID, over a selector tied to incidental markup.
Free tools Windows power users keep installed
One-click scans. No signup required.
Set up and update snapshot baselines deliberately
- Write the visual test. Add a
toHaveScreenshot()assertion to a Playwright Test test file and ensure the page is in its intended state before capture. - Generate the first reference. Run the relevant test with your project’s normal Playwright command. The initial run creates the snapshot rather than validating it against a prior image.
- Review the generated file. Confirm that it shows the expected page, viewport, data, and state. A generated snapshot is not automatically an approved design baseline.
- Commit the reference. Keep snapshots in version control so code changes and visual changes can be reviewed together.
- Review later diffs. When an assertion fails, inspect the actual image, expected image, and diff artifacts before deciding whether the UI or test setup should change.
- Refresh only after approval. Run
npx playwright test --update-snapshotswhen a deliberate, reviewed interface change should become the new reference. Check the resulting snapshot changes before committing them.
Snapshot locations can be configured in Playwright. If a test cannot find its expected image, check the configured snapshot path and the test’s snapshot naming before regenerating files. Regeneration is a baseline update, not a fix for an unexplained failure.
Make captures stable before tuning tolerance
Image comparisons are sensitive to the rendering environment. Operating system, browser version, settings, hardware, power source, and headless mode can all affect pixels. Generate and compare baselines in a consistent environment where possible—especially in CI—and avoid casually mixing local baselines with differently rendered CI screenshots.
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
Control page state
Make the conditions that affect the image deterministic before the assertion runs:
- Use predictable test data rather than live or changing records.
- Fix or control time-dependent content, such as timestamps and countdowns.
- Wait for the meaningful page state, not just the initial navigation event. For example, wait for a known heading or component to appear.
- Make the relevant interaction state explicit: open the same menu, select the same tab, or dismiss the same dialog each run.
- Keep network-dependent content consistent. If a third-party widget is not part of the UI under test, consider controlling or excluding it rather than allowing its response to vary.
Playwright screenshot assertions disable animations by default. You can also mask volatile regions or apply a stylesheet to suppress dynamic content. Moving the mouse away before capturing can prevent hover styling from changing the image.
test('stable account panel', async ({ page }) => {
await page.goto('https://example.com/account');
await page.getByRole('heading', { name: 'Account' }).waitFor();
await page.mouse.move(0, 0);
await expect(page).toHaveScreenshot('account.png', {
mask: [page.locator('[data-testid="live-clock"]')],
stylePath: './tests/visual-stability.css'
});
});For example, the stylesheet might hide a known animated or rotating region:
/* tests/visual-stability.css */
[data-testid="rotating-promotion"] {
visibility: hidden !important;
}Masking or hiding content is appropriate only when that content is outside the visual behavior you intend to test. If a masked region is itself important, write a separate assertion for it instead of concealing it.
Rank #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.
Choose comparison tolerances based on the failure you can accept
Playwright exposes three useful controls. threshold governs the acceptable perceived color difference at an individual pixel. The pixelmatch comparator uses the YIQ color space and documents a default threshold of 0.2; zero is strict and one is lax. maxDiffPixels caps the absolute number of differing pixels, while maxDiffPixelRatio caps the share of the image that may differ. The total-difference limits are unset unless you configure them.
| Option | What it limits | When it may help |
|---|---|---|
threshold |
Per-pixel perceived color difference. | When known rendering variation changes color values slightly across otherwise acceptable pixels. |
maxDiffPixels |
Maximum number of differing pixels. | When an absolute cap makes sense for a fixed-size image or focused component. |
maxDiffPixelRatio |
Maximum proportion of the screenshot area that may differ. | When the acceptable diff should scale with image dimensions. |
You can set tolerances on an individual assertion or in expect.toHaveScreenshot configuration. For example:
Recommended Free Tools
await expect(page).toHaveScreenshot('dashboard.png', {
threshold: 0.2,
maxDiffPixels: 120
});Those values illustrate the configuration shape, not a universal recommendation. Pick limits based on a known, acceptable source of rendering variation and the regressions your project needs to catch. Start strict enough to reveal meaningful changes, inspect failures, and change a limit only when the diff is understood. Increasing tolerance broadly can hide genuine layout or color regressions.
Diagnose a failed visual comparison
When the assertion fails, inspect Playwright’s expected, actual, and diff artifacts. Identify where and how the image changed before updating the reference or weakening the assertion.
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.
| Symptom | Likely cause | Useful next step |
|---|---|---|
| Many tests fail after a browser or CI environment change. | The baseline and current capture may be rendered by different browser versions, operating systems, settings, or headless configurations. | Run both baseline creation and comparison in the same controlled environment, then review whether new references are genuinely required. |
| A small region changes between runs. | Dynamic data, time, animation, a third-party widget, or hover state may be varying. | Stabilize the state; wait for the target; move the pointer away; mask or style out only irrelevant volatility. |
| The whole page is noisy, but the component looks correct. | The assertion may include unrelated regions that change independently. | Use a locator screenshot assertion for the component under test, or isolate volatile regions deliberately. |
| The test reports a missing expected snapshot. | This may be the initial run, a changed snapshot path, or a naming/configuration mismatch. | Check the assertion name and snapshot configuration; generate and review a baseline only if this is an intentional new reference. |
| A test passes despite a visible difference. | Configured per-pixel or total-difference tolerance may be too permissive for the affected image. | Review the diff and tighten the relevant limit. Keep tolerance changes specific to the known rendering issue. |
| A snapshot update creates unexpected image changes. | The test may have run with unstable page data or a changed rendering environment. | Do not commit the files blindly. Reproduce in the intended environment, stabilize the capture, and inspect the new references. |
Use local snapshots or hosted review?
Built-in Playwright snapshots are a straightforward starting point when your team can keep image baselines with the tests, review diffs in the repository, and make CI rendering consistent. This keeps the comparison in the test workflow, but your team owns baseline organization and review discipline.
Percy is an optional hosted route. BrowserStack documents an integration that routes existing toHaveScreenshot() calls to Percy, compares screenshots in the cloud, maintains a base build, and presents visual changes for review. That changes how visual updates are reviewed: decide whether a difference should fail a job immediately or wait in an approval workflow. The vendor guide lists Node.js 18+, @playwright/test 1.60+, @percy/cli 1.32.6+, and @percy/playwright 1.1.2+ for its documented drop-in path; verify current compatibility and service terms in the vendor guide before adopting it. Pricing and accuracy comparisons are not established here.
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 reinstallOutdated 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 matchFor screenshot capture outside a Playwright test assertion—for example, to obtain a clean page image through an API or let an AI agent request a screenshot—try ScreenshotNeo first. It is a screenshot API and MCP server; it is not a replacement for reviewing and maintaining Playwright’s visual-test baselines.
Or skip the browser setup
If your immediate need is a screenshot file rather than a Playwright visual assertion, ScreenshotNeo returns a PNG, JPEG, WebP, or PDF from one GET request. Here is the cURL form, adapted to capture the page you choose:
curl -G "https://api.screenshotneo.com/v1/shot"
-d access_key=YOUR_API_KEY
--data-urlencode url=https://example.com
-o shot.webpSee the ScreenshotNeo API documentation for request options and setup. Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server provides screenshot tools for AI agents, and 1,000 screenshots a month are free without a card; paid plans start at $5 for 3,000 shots. The API’s capture and cleanup behavior is separate from Playwright’s pixel-baseline assertions.
Sign up free for 1,000 screenshots a month, with no card required.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Frequently Asked Questions
Can I use Playwright screenshot assertions without Playwright Test?
No. The `toHaveScreenshot()` assertion is provided through the Playwright Test runner.
Does Playwright create the expected image on the first run?
Yes. The initial execution creates the reference snapshot; review and commit it before relying on later comparisons.
Can I compare a single element instead of a full page?
Yes. Use `toHaveScreenshot()` on a locator to focus the capture on a component or region.
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.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errors
