Best Practices

Visual testing baseline management: screenshots as decisions

Baselines aren't just images—they're records of accepted visual intent. Treat baseline updates with the same care as code changes, and visual testing becomes trustworthy.

Join the waitlist

What a baseline represents

A baseline is the accepted visual state of your UI at a point in time. It's a decision: "this is how this component/page should look."

When you update a baseline, you're not just making a test pass. You're declaring that the new visual state is intentionally correct and should be protected going forward.

This framing matters. Teams that treat baselines as "whatever makes the test green" end up with visual tests that don't catch anything meaningful.

Common baseline failure modes

Most teams don't fail at capturing screenshots. They fail at managing what those screenshots mean over time.

Accidental approvals

Someone updates baselines without understanding the change. Regressions become the new 'expected' state.

Noisy bulk updates

Environmental changes trigger hundreds of diffs. Teams approve everything to unblock, losing signal.

Branch confusion

Baselines updated on one branch conflict with another. Merges become visual testing nightmares.

Lost context

Weeks later, no one remembers why a baseline was updated. Was it intentional? Was it reviewed?

Each of these erodes confidence. Eventually, the team stops trusting visual tests—or stops running them entirely.

A sane baseline policy

Good baseline management isn't about tooling. It's about treating visual changes as decisions that deserve review and documentation.

Intentional updates only

Baselines change because design changed, not because tests failed. The question is 'should this be the new baseline?'—not 'how do I make tests pass?'

Clear ownership

Every baseline update should have an owner who understands and approves the visual change. Anonymous updates erode trust.

Documented intent

Link baseline updates to issues, design specs, or decisions. Future you will want to know why this changed.

Review before merge

Baseline updates should go through the same review process as code changes. A diff viewer helps reviewers understand what changed.

This takes discipline, but it pays off. Teams with rigorous baseline policies actually trust their visual tests.

Audit trail mindset

Six months from now, someone will ask: "Why does this component look this way? When did it change?"

If your baseline updates are tied to issues, reviewed in PRs, and documented with intent, you can answer. If baselines were bulk-approved to unblock a pipeline, you can't.

This traceability matters for engineering managers and designers who need confidence in visual consistency. See approval workflows and designer-approved testing for more on building this confidence.

Avoid the baseline churn trap

If you're updating baselines constantly, something is wrong upstream:

  • Environmental flakiness: Tests fail for reasons unrelated to real changes. See reducing flakiness.
  • Too many snapshots: You're testing more than you can maintain. Reduce scope to meaningful coverage.
  • Rapid design iteration: Maybe visual testing is premature for this area. Focus on stable, contracted UI.

Baseline updates should be occasional and intentional, not a regular part of every PR.

Quick checklist

  • Define what triggers a baseline update (design change, not test failure)
  • Assign ownership for baseline approval per area
  • Require documented intent for every baseline update
  • Use visual diff tools for clear before/after review
  • Treat baseline updates like code changes (review required)
  • Establish process for handling environmental drift
  • Document baseline management process for the team

Related guides

How to reduce visual testing flakinessVisual diff approval workflowsVisual testing in CI pipelinesDesigner-approved visual testingVisual regression testing fundamentals

Frequently Asked Questions

Should screenshot baselines be committed to git?
It's one valid approach that provides version control and easy rollback. Downsides include repository bloat and merge conflicts. Alternative approaches store baselines externally with version references. Choose based on your team size and test volume.
Who should approve baseline updates?
Ideally, someone who understands the visual intent—often a designer for UI components, or a tech lead for functional screens. The key is that approval comes from someone with context, not just anyone trying to make tests pass.
How often should we update baselines?
Only when design intentionally changes. If you're updating baselines frequently without corresponding design work, something is wrong—either tests are too brittle or changes aren't being communicated.
How do you avoid accidental baseline changes?
Make baseline updates explicit and reviewable. Require separate commits or PRs for baseline changes. Use tooling that shows diffs clearly. Never auto-approve baselines without human review.
What's the best way to review baseline updates?
Use visual diff tools that show before/after comparisons clearly. Review in context of the associated code change. Ask: 'Is this change intentional? Is it correct? Does it match design intent?'
How do teams handle multiple release branches?
Baselines typically live with the branch they represent. When branching for releases, baselines fork too. Merging requires careful attention to which visual state should survive—usually the more recent intentional design.
What if baselines get out of sync?
Treat it as a bug to be fixed, not ignored. Identify the root cause: environmental drift, missed updates, or actual regressions. Re-establish baselines from a known-good state with full review.
How do you handle temporary visual states?
For experiments or A/B tests, consider separate baseline sets or skip visual testing for those variants. Don't pollute your main baselines with temporary states that will change.

Join the waitlist for better baseline management

Get early access