Run Playwright tests against the existing baselines first, investigate every failure, and only then refresh the snapshots you have confirmed should change. Use an explicit update mode, inspect the expected, actual, and diff images, and commit reviewed baseline files with the application change. Updating a snapshot changes what the test expects; it does not prove the new appearance is correct.
Use a review-first update workflow
-
Run the relevant tests without update mode
Run the affected Playwright tests normally so failures remain visible against the existing references. Do not begin with
--update-snapshots: first establish which assertions fail and what the browser actually rendered.As an Amazon Associate I earn from qualifying purchases.
-
Decide whether each difference is intended
Compare the expected and actual images, then inspect the application change that produced the difference. If you cannot explain a changed region, treat the failure as unresolved; do not replace its baseline just to make the run pass.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Update only the intended snapshots
For a focused refresh, run
npx playwright test --update-snapshots=changed. This tells the CLI to update changed snapshots. Use an explicit mode rather than relying on an unqualified update setting, since defaults and behavior can vary by installed Playwright version. -
Review the generated images and code
Inspect the expected image, actual image, and diff for each changed test. Review the related application code as well: a visually plausible baseline can still encode an unintended bug. Playwright Trace Viewer can show screenshot comparisons alongside test context, including browser and viewport information.
-
Commit only reviewed expectations
Snapshot files are test expectations. Commit the approved changes with the application change in version control so reviewers can assess both together.
Choose the update mode deliberately
| Mode | What it does | When it fits |
|---|---|---|
changed |
Updates changed snapshots. | A targeted refresh after confirming the visual changes are intended. |
all |
Regenerates all snapshots. | A deliberate broad refresh when you are prepared to inspect every affected baseline. |
missing |
Creates missing snapshots. | Adding a baseline where none exists. |
none |
Prevents snapshot updates. | Ensuring a run cannot change expected images. |
Check the CLI help for the Playwright version installed in your project before relying on a mode or default. The current CLI documentation includes these modes, and Playwright release notes record changes to update behavior. Explicitly passing the mode makes scripts and review steps easier to understand.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Interpret the diff in its rendering context
expect(page).toHaveScreenshot() waits for two consecutive screenshots to match before comparing the latest capture with the expectation. By default, animations are disabled: finite animations are fast-forwarded and infinite animations are canceled for capture, then played again. These steps reduce capture variability; they do not determine whether a change is desirable.
Rendering can vary with the host operating system, browser version, settings, hardware, power source, and headless mode. When possible, generate and verify baselines in a consistent environment. When investigating a difference, consider the browser project and viewport alongside all three images rather than treating a single pass/fail result as the full diagnosis.
Keep tolerances and exclusions narrow
Screenshot assertions support threshold, maxDiffPixels, and maxDiffPixelRatio. These options permit specified visual or pixel-level differences, so increasing them can allow changes to pass without review. Adjust them narrowly for a known source of rendering noise, and inspect the changed region instead of raising a limit until the assertion succeeds.
You can use masks for selected locators and a stylePath stylesheet to hide or alter dynamic content, including in shadow DOM and frames. These controls are useful for genuinely nondeterministic details, but broad exclusions can conceal regressions. Target only the volatile value or region, document why it is excluded, and leave meaningful surrounding layout and content visible.
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot common snapshot-update problems
- The test passes after updating, but the UI looks wrong: Updating replaced the expected image; it did not validate the product change. Compare the diff and inspect the associated code before accepting the baseline.
- The command changes more files than expected: Check the mode and installed Playwright version. Use
--update-snapshots=changedfor changed snapshots rather than a broad mode such asall, and inspect the resulting file list. - A snapshot differs between machines: Compare the operating system, browser version, settings, hardware, power conditions, headless mode, browser project, and viewport. Re-run and verify in a consistent environment where practical.
- Dynamic content causes repeated diffs: Identify the specific unstable content, then consider a narrowly scoped locator mask or
stylePathrule. Confirm that surrounding content and layout remain tested. - Small rendering noise causes failures: Determine its source before changing comparison settings. If a tolerance is warranted, adjust it narrowly and review the affected pixels; permissive limits can hide real differences.
- You need to add a baseline without refreshing existing ones: Use the
missingmode, then review the created snapshot like any other test expectation.
Or skip the browser setup
If you need a standalone screenshot of a page rather than a Playwright test baseline, ScreenshotNeo can return an image or PDF from one GET request. For example, this cURL request saves a WebP screenshot; see the ScreenshotNeo API documentation for options and setup.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and 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 or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free 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.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems
