## TL;DR

Use maxDiffPixelRatio for proportional tolerance (0.01 is a sane start) and mask dynamic regions like timestamps and ads; tune per screenshot, never globally, and only raise tolerance for proven noise.

## The query

```text
playwright expect().toHaveScreenshot() threshold tuning
```

## Use this when

- screenshot tests flake on rendering noise
- a new machine fails all visual tests
- animations break pixel diffs

## Not for

- real visual regressions (fix the UI instead)
- first screenshot baselines
- full-page vs viewport size mismatches

## Steps

1. Open the diff artifact from a failing run and identify the noise: anti-aliasing, fonts, timestamps, animations. Expected output: a named cause for the diff, not a guess.
2. Mask dynamic regions with the mask option or a stylesheet that freezes animations. Expected output: the masked areas no longer contribute to the diff.
3. Set maxDiffPixelRatio starting at 0.01 on that one assertion and re-run. Expected output: the assertion passes on identical renders.
4. Run the suite several times, including on CI, and only raise the ratio if the same noise fails again. Expected output: stable passes across runs and machines.
5. Document the chosen tolerance next to the assertion so the next person knows it was deliberate. Expected output: a comment stating the ratio and the noise it covers.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_O1w7Y7tsX5fSCR9nPgXHVg