Percy baseline update flaky diffs

If your Percy baseline updates are flaky, the usual cause is that the visual changes aren’t fully deterministic between runs. Here are the most common causes and fixes:

Common causes

• Animation / transitions still running
  • Disable CSS transitions/animations in tests.
• Dynamic content
  • Timestamps, random IDs, ads, rotating banners, personalized content, live data.
• Fonts not fully loaded
  • Wait for web fonts before capturing.
• Network race conditions
  • Data still loading when Percy snapshots are taken.
• Viewport differences
  • Slight size changes, browser/device differences, responsive breakpoints.
• Anti-aliasing / rendering variance
  • OS/browser updates can cause pixel differences.
• Parallel test ordering
  • Baselines being updated from multiple jobs at once.

Stabilization tips

• Freeze or mock all dynamic data.
• Wait for the page to be “ready” before snapshot:
  • all API calls complete
  • fonts loaded
  • animations finished
• Use a fixed viewport and browser version.
• Disable caret blinking, scrolling changes, and hover states.
• Run Percy updates from a single, consistent CI environment.
• Avoid updating baselines on unstable branches or from concurrent jobs.

In Percy-specific terms

• Make sure you’re not updating baselines while tests are still in flux.
• If multiple builds are setting the same snapshots, ensure only one is allowed to update baselines.
• Review whether you need to ignore regions for unavoidable dynamic areas.

Practical next steps

1. Compare several failing Percy runs to see if the diff location changes.
2. Identify whether the changed area is dynamic or rendering-related.
3. Add waits/mocks/disabled animations.
4. Re-run on the same environment repeatedly to confirm stability.
5. Only then update the baseline.

If you want, I can help you debug a specific Percy flaky diff by looking at:

• your test framework,
• the Percy integration,
• and an example snapshot/diff pattern.