The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →To capture and compare a meaningful UI state in Playwright, perform the interaction that creates it, assert the expected behavior, then use Playwright Test’s await expect(page).toHaveScreenshot('state-name.png'). The first run creates a reference image; later runs compare against it. Review that initial image and every meaningful diff rather than accepting snapshots blindly.
Build the test around a meaningful interaction
A screenshot is most useful after the page has reached a deliberate, user-visible state—not merely after navigation. Use locators and actions to reproduce the state a reviewer needs to inspect, such as an opened dialog, selected tab, validation message, or completed navigation. Then assert the important behavior directly before checking its appearance.
import { test, expect } from '@playwright/test';
test('shows the confirmation dialog after saving', async ({ page }) => {
await page.goto('/settings');
await page.getByRole('button', { name: 'Save changes' }).click();
await expect(page).toHaveURL(/settings/);
await expect(page.getByRole('dialog')).toContainText('Changes saved');
await expect(page).toHaveScreenshot('settings-saved-dialog.png');
});The URL and dialog-text checks express behavioral requirements; the screenshot checks rendered appearance. A visual comparison does not replace semantic assertions, and semantic assertions do not show whether layout, spacing, color, or other rendered details changed. Playwright’s assertions guide documents the test runner’s assertion options.
Choose the screenshot scope
Use a page assertion when the whole visible page state is the contract, or a locator assertion when only one component needs visual review. Use full-page capture when content below the viewport matters; use a clipped region when the test should compare a specific area. These choices change what a passing comparison covers.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problems#1 Best Overall
// Compare a particular component.
await expect(page.getByRole('dialog')).toHaveScreenshot('save-dialog.png');
// Capture a full-page reference.
await expect(page).toHaveScreenshot('settings-full-page.png', {
fullPage: true,
});
// Compare a specified region of the page.
await expect(page).toHaveScreenshot('settings-panel.png', {
clip: { x: 0, y: 0, width: 800, height: 600 },
});Consult the current PageAssertions API reference for the available options and their behavior in your installed Playwright version. Screenshot assertions were added in v1.23; individual options can have later version requirements—for example, stylePath is documented as added in v1.41.
Create and review baselines deliberately
- Run the test for the first time. Playwright creates an expected image when no baseline exists. Treat it as a proposed reference: inspect it to confirm it shows the intended state and is free of transient or unintended content.
- Commit reviewed references. Keep the baseline images with the test code so changes can be reviewed alongside code changes.
- Run again in a consistent environment. Playwright notes that rendering can vary with host operating system, browser version and settings, hardware, power source, headless mode, and other factors. Use consistent browser and platform settings for comparisons; where projects intentionally cover different environments, keep their baselines distinct.
- Inspect each later diff in context. Decide whether it represents a real UI change, a test-state problem, or incidental content before updating the reference. A baseline update changes what future runs treat as expected.
Playwright’s Visual comparisons guide explains baseline generation, updating snapshots, and cross-environment variation. Generated baseline names can include browser and platform identifiers, which helps keep environment-specific references separate.
Reduce incidental differences without hiding real regressions
First make the tested state deterministic. If genuinely volatile content remains, use a narrowly scoped control and understand what it excludes from review.
- Animations: Screenshot assertions disable animations by default. Finite animations are fast-forwarded; infinite animations are canceled to their initial state for the screenshot and resumed afterward. This helps avoid capturing an arbitrary animation frame.
- Mask changing regions: Mask timestamps, rotating content, or other values that are expected to vary but are not part of the visual contract. Keep the mask as narrow as practical so unrelated changes remain visible.
- Apply a screenshot stylesheet: A stylesheet can hide or normalize volatile elements. Playwright documents that this stylesheet applies through Shadow DOM and inner frames. Use it only when the normalization matches the intent of the test.
- Capture the relevant region: A locator screenshot or clip can exclude unrelated page regions, but it also means changes outside that region will not be checked.
- Set a difference tolerance cautiously:
maxDiffPixels,maxDiffPixelRatio, and the perceptualthresholdcontrol how much image difference is accepted. They are tolerance settings, not evidence that a visible change is harmless. Choose and document a tolerance based on the test’s purpose rather than widening it to silence an unexplained diff.
See the PageAssertions API and visual comparison documentation for supported screenshot controls and details.
Diagnose failures with the diff and trace
Use the screenshot diff to identify what rendered differently. If the cause is unclear, inspect the test trace: it gives context around the action sequence and lets you examine DOM snapshots and execution details near the failure. This can reveal that the test reached a different state, an action did not have the expected effect, or a page element changed before capture.
- Open the failed test’s trace in the Trace Viewer.
- Review actions leading up to the screenshot and the DOM snapshots around the failure.
- Check whether the test reached the intended UI state and whether the difference is a product change or unstable input.
- Fix the interaction or stabilize only the identified source of noise; update the baseline only if the new appearance is intended.
Use visual checks alongside other kinds of review
Visual screenshots compare rendered pixels. Focused assertions check properties such as text, URL, title, or form value. ARIA snapshots describe accessible structure. These checks answer different questions: combine them when the state merits behavioral, accessibility-structure, and visual coverage rather than expecting one snapshot type to stand in for the others. Playwright’s ARIA snapshots documentation explains the accessible-tree view.
For screenshot comparisons, Playwright recommends toHaveScreenshot(). The SnapshotAssertions API cautions against using toMatchSnapshot() for screenshots. Screenshot assertions are for the Playwright Test runner; do not assume the same assertion workflow is available outside it.
Common problems and fixes
- The screenshot differs between machines: Rendering may vary with the operating system, browser version, settings, hardware, power source, or headless mode. Align the comparison environment or maintain separate baselines for intentionally different projects.
- The test captures an inconsistent state: Confirm the interaction and direct assertions have reached the intended state. The screenshot assertion waits for two consecutive screenshots to match before comparing, but that stability check does not establish that the page is in the correct application state.
- A date, rotating item, or live value creates diffs: Mask only that region or apply a screenshot stylesheet if the content is irrelevant to this test. Do not hide a region whose visual behavior is under test.
- A tolerance makes unexplained changes pass: Re-examine the diff, test intent, and environment. Tighten or remove the tolerance unless the allowed variation has a specific, defensible reason.
- The test uses the wrong screenshot assertion: Use
toHaveScreenshot()for screenshot comparison, and confirm the option you need exists in your installed Playwright release. - The image alone does not explain the failure: Open the trace to inspect the preceding actions, DOM snapshots, and execution details.
Or skip the browser setup
If you need an image of a URL without writing a Playwright interaction test, ScreenshotNeo is a website screenshot API and MCP server for developers. This is a separate capture workflow, not a replacement for Playwright’s interaction-based visual assertions.
Recommended Free Tools
One GET request returns an image or PDF. Example using 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 details. Cookie banners, newsletter popups, and chat widgets are removed before capture; 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
Does `toHaveScreenshot()` compare a screenshot on the first run?
No. The first run creates the reference image; subsequent runs compare their capture with that baseline.
Can I use Playwright screenshot assertions without Playwright Test?
The documented screenshot assertion workflow is for the Playwright Test runner; check the API notes before relying on it elsewhere.
What is the difference between a visual screenshot and an ARIA snapshot?
A visual screenshot captures rendered appearance, while an ARIA snapshot represents accessible structure. They complement one another rather than serving as substitutes.
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.
