Use Playwright Test’s toHaveScreenshot() assertion and tune two separate limits: threshold controls how sensitive the comparison is to color differences in each pixel, while maxDiffPixels or maxDiffPixelRatio sets how many differing pixels the whole screenshot may contain. For example:
import { test, expect } from '@playwright/test';
test('homepage visual baseline', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot({
threshold: 0.1,
maxDiffPixels: 100,
});
});Playwright’s documented screenshot matcher and options are described in its PageAssertions API and visual comparisons guide.
As an Amazon Associate I earn from qualifying purchases.
What the pixel threshold controls
threshold controls how much perceived color difference between corresponding pixels Playwright will tolerate before identifying a pixel as different. The comparator uses the YIQ color space. Playwright documents a range from 0 (strict) to 1 (lax), with a default of 0.2. Lowering it makes the comparison more sensitive to subtle color changes; raising it can cause subtle changes to disappear from the diff. See the TestConfig reference.
Set the total number of differences allowed
The per-pixel threshold does not limit how much of the image can differ. Use one of these additional options to set that aggregate allowance:
#1 Best Overall
| Option | What it limits | When to use it | Default |
|---|---|---|---|
maxDiffPixels |
Absolute number of pixels treated as different | When the tolerated pixel count itself matters | Unset |
maxDiffPixelRatio |
Fraction of the screenshot’s pixels treated as different, from 0 to 1 | When the tolerated share should scale with screenshot size | Unset |
Both options are documented in the PageAssertions API and visual comparisons guide. These aggregate limits answer a different question from threshold: a permissive per-pixel setting can overlook small color shifts, while an overly generous count or ratio can allow a broad change to pass. Pick values according to what your team considers meaningful, and inspect the diff when changing tolerance; there is no universally correct tolerance for every interface.
Set defaults in the Playwright config
Place shared screenshot assertion values under expect.toHaveScreenshot in the Playwright configuration. An individual assertion can still provide options for a case that needs different tolerance.
import { defineConfig } from '@playwright/test';
export default defineConfig({
expect: {
toHaveScreenshot: {
threshold: 0.1,
maxDiffPixels: 100,
},
},
});The values above are an example, not a recommended universal project policy. Start with a policy suited to your screenshots and the visual risk of your application.
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 →Choose the screenshot assertion, not a generic snapshot matcher
For a page, use expect(page).toHaveScreenshot(); for a particular element, use the corresponding locator screenshot assertion. The matcher is part of Playwright Test and waits until two consecutive screenshots produce the same result before comparing the latest screenshot with its expected baseline. The SnapshotAssertions reference specifically recommends toHaveScreenshot() for screenshot comparisons rather than using toMatchSnapshot on a screenshot buffer.
Reduce capture noise before loosening tolerance
- Keep the browser, viewport, and test environment consistent with the baseline.
- Control dynamic content. If a region is genuinely volatile and irrelevant to the test, use screenshot styling or masking where appropriate rather than increasing tolerance for the whole image.
- Check the generated comparison to determine whether each difference is noise or a real interface change.
- Adjust per-pixel sensitivity and the total pixel allowance separately, then review the outcome. A passing assertion does not establish that every visual change is harmless.
Playwright’s visual comparison guide describes applying a stylesheet during capture to filter dynamic elements. It also notes that hover effects are captured in the state present at capture time, so avoid unintended hover states in test setup.
Troubleshoot failing or misleading comparisons
- Small color changes fail unexpectedly: Check whether
thresholdis too strict for the image. Increase it cautiously and inspect the diff; higher values can hide subtle changes. - A large visual change passes: Review whether
maxDiffPixelsormaxDiffPixelRatiois too generous. A high aggregate allowance can let a broad regression through. - Repeated runs produce different diffs: Stabilize volatile page content and capture state before adjusting thresholds. Check for unintended hover effects and use screenshot styling or masking only for irrelevant dynamic regions.
- The assertion compares the wrong image or area: Confirm that the test uses the intended page or locator screenshot assertion and that the viewport and test environment match the baseline.
- A generic snapshot comparison is being used: Switch screenshot comparisons to
toHaveScreenshot(), as recommended in Playwright’s SnapshotAssertions reference.
Or skip the browser setup
If you need a rendered website capture rather than a Playwright visual-regression assertion, ScreenshotNeo provides a screenshot API and MCP server. One GET request returns an image or PDF:
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 options. Cookie and consent banners, newsletter popups, and chat widgets are removed before the capture; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers indicate the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDFs. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month, with no card required.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Frequently Asked Questions
Can I set both maxDiffPixels and maxDiffPixelRatio?
The documented options provide either an absolute differing-pixel allowance or a ratio allowance. Choose the measure that matches your requirement; the cited references do not establish a precedence rule for setting both together.
Does threshold set how many pixels can differ?
No. It controls the per-pixel color sensitivity. Use maxDiffPixels or maxDiffPixelRatio to limit the aggregate number or share of differing pixels.
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.
