visual regression: how to update baselines after intentional UI change

TL;DR

Intentional UI changes require new baselines, but every diff must be human-reviewed first. Review the diff images, accept the intended changes, and reject anything unexpected before updating.

Error

(Not an error; a workflow. Trigger: visual tests fail because the design changed deliberately.)

Steps

1. Open the diff report and review every changed image. Expected: you confirm each change is intended.
2. If any diff is unintended, file it as a bug instead of updating. Expected: no rubber-stamping.
3. Accept the intended diffs in the visual tool (Percy, Chromatic, Playwright snapshots). Expected: baselines updated.
4. Note the design change in the PR. Expected: reviewers know the baselines moved deliberately.
5. Re-run. Expected: green on the new baselines.

When to use

• Deliberate redesigns or component updates.
• Baseline updates as a planned step.

When not to use

• Unexpected diffs (investigate as bugs).
• You are tempted to bulk-accept without review.

Tool compatibility

• Percy, Chromatic, Playwright toHaveScreenshot.

Variant phrasings

Update visual baselines

The task; review-then-accept is the workflow.

Accept visual diffs after redesign

Same thing; the review is the point.

Why it happens

Baselines encode the old design. A deliberate change makes them stale, but blind acceptance would also accept regressions.

Edge cases

• Font and rendering differences across platforms cause false diffs; pin the environment.
• Animate-heavy UIs need freeze-frame setup before screenshots.
• Baseline branches should match the code branches.

Provenance

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