Visual regression: baseline management on the main branch in CI
Visual tests are only as good as their baselines. The authoritative baseline should live on the main branch, update only when a change is intentionally approved, and be what pull requests compare against. Ad hoc or missing baselines cause noisy, untrustworthy diffs.
What this error means
Every PR shows unrelated visual changes, or baselines drift so far that developers rubber-stamp diffs. Committed baselines are stale, missing for some platforms, or updated inconsistently across branches.
# PR shows 40 "changed" stories that the PR did not touch,
# because the baseline on main was never refreshed after the last design changeCommon causes
No single source of truth for the baseline
Baselines are updated on random branches or laptops, so different runs compare against different references and diffs become noise.
Baselines not refreshed after an intended change
A design change merged without updating the baseline, so every later PR keeps showing the same stale diff.
How to fix it
Anchor the baseline on main and update it there
- Treat the baseline captured on main as authoritative.
- When a change is intentional, update baselines in that PR so main always reflects the current design.
- Compare PR runs against the main baseline, not against each other.
# in the merge-to-main workflow, refresh the accepted baseline
npx playwright test --update-snapshots
git add '**/*-snapshots/**' && git commit -m "chore: update visual baseline"Use branch-aware baselines in hosted tools
Percy, Chromatic, and Applitools track baselines per branch. Configure the base branch so PRs diff against the accepted main baseline and merges promote it.
Configuration config = new Configuration();
config.setBaselineBranchName("main");How to prevent it
- Keep the authoritative baseline on the main branch.
- Update baselines only as part of an intentional, reviewed change.
- Configure hosted tools to diff PRs against the main baseline.