Why Percy Snapshots Differ Between Local and CI Runs
Local and CI Percy diffs can come from different baselines, snapshot identities, capture timing, or rendering inputs. Use this checklist to find the cause.
Local and CI Percy snapshots differ when the runs capture different UI states or rendering inputs, or when Percy compares them against different baselines. A visual diff shows that the captured result differs from the selected baseline; by itself, it does not tell you whether the UI changed or the baseline is wrong.
Diagnose in this order: verify the Percy project and build context, check baseline selection and snapshot identity, compare the capture inputs, then confirm both runs capture the same settled state. Only after that decide whether to approve a real UI change or ignore a genuinely volatile region.
1. Confirm the project and build context
Check that both runs use the intended Percy project token and the same Percy integration or CLI invocation. A missing or different token can send a run to the wrong project or prevent the expected upload.
- Confirm the token is present in both local and CI environments and belongs to the same Percy project.
- Inspect the build’s branch and target-branch context.
- Confirm which approved baseline Percy selected for each build. Do not assume two builds compare against the same reference just because they use the same test.
Percy’s integration documentation shows the CLI wrapping test commands and the project token supplied through the environment. See Percy CI integration guidance and baseline workflows.
2. Compare baseline selection and snapshot identity
Compare the complete snapshot names in the local and CI runs, along with the branch and baseline each build uses. Keep names stable. A renamed snapshot can behave like a new baseline identity, while an unexpected branch context can select a different reference.
Make locale, country, brand, and other variants explicit. Each variant should have its own expected baseline structure. Comparing one locale with another can produce a misleading diff or a no-baseline result. Percy’s locale guidance discusses variant baselines and the consequences of changed snapshot names: Percy locale variants.
| Symptom | Check first |
|---|---|
| “No baseline” or a new snapshot appears | Snapshot name, locale or variant, project, branch, and target branch |
| A diff appears against an unexpected page or locale | Variant naming and the baseline structure |
| Local and CI builds show different comparison references | Build context and selected approved baseline |
3. Match the inputs that produce the page
Compare the actual inputs to the UI, not just the test code. Differences in any of these can create real pixel changes:
- Viewport widths and browser or test configuration
- Locale, timezone, and geolocation-sensitive content
- Feature flags, application data, account state, and session state
- Network responses, API fixtures, and test ordering
- Fonts, images, stylesheets, and other assets available at capture time
Percy renders submitted snapshots in its service environment across configured browsers and responsive widths; the local browser environment does not necessarily match that rendering environment. Compare the configured capture widths and browser matrix, and ensure the same intended data and assets are available in both runs. See Percy visual testing documentation.
4. Capture only after the intended state is ready
A test can pass while taking a screenshot too early. Ensure the page has reached the same user-visible state before calling the Percy snapshot API. Wait for relevant asynchronous requests and lazy-loaded content; make sure fonts and assets have loaded when they affect layout.
Control or account for animations, clocks, random identifiers, rotating banners, and personalized content when they can change the image between runs. Use an ignore region only for a genuinely expected dynamic area. An ignore region cannot repair a wrong baseline, mismatched locale, or unstable capture point.
Percy’s client documentation describes the snapshot API and capture options. Check the documentation for the integration in use, such as Percy client documentation, and ensure snapshot names are unique where required by that integration.
5. A practical local-versus-CI checklist
- Confirm project: Compare the Percy project and token source for both runs.
- Confirm comparison: Record the branch, target branch, build context, and selected baseline.
- Confirm identity: Compare full snapshot names and explicit locale or variant values.
- Confirm inputs: Match viewport widths, browser configuration, data, flags, locale, and session state.
- Confirm readiness: Capture after relevant requests, lazy content, fonts, and assets are settled.
- Classify the difference: Fix project or baseline organization for a comparison mismatch; investigate rendering inputs for a real visual difference; approve an intentional UI change through the team’s baseline process.
Why is Percy showing a diff when I did not change the UI?
“No code change” does not guarantee identical pixels. Check whether Percy selected the same baseline, then compare data, locale, viewport, assets, asynchronous readiness, and dynamic content. A diff can also be expected if a dependency, font, or response changed outside the application code you edited.
Why does Percy say there is no baseline?
First check whether the snapshot name changed or the run uses a different project, branch, target branch, or locale variant. A renamed snapshot or a variant without its corresponding baseline can appear as a new snapshot. Correct the identity or baseline organization before treating it as a rendering problem.
Are local screenshots rendered the same way as Percy CI snapshots?
Not necessarily. Percy processes submitted snapshots in its service environment using configured browsers and responsive widths. Local browser conditions may differ, so compare the test’s capture inputs and the Percy build’s rendering configuration as separate parts of the investigation.
When should I approve a diff or ignore a region?
Approve a diff when it represents the intended UI and the comparison is against the correct baseline. Ignore a region only when its changing content is expected and irrelevant to the visual check. Neither action should be used to hide a wrong project, mismatched variant, or capture taken before the page is ready.
Or skip the browser setup
If you need a standalone screenshot to inspect or share a page while debugging, ScreenshotNeo captures a URL with one API request. It is a website screenshot API and MCP server; Percy remains the baseline comparison workflow described above. Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSign up for 1,000 free screenshots a month, with no card required.
FAQ
Can ignore regions fix a missing baseline?
No. Ignore regions affect image comparison; they do not create or select the expected baseline. Resolve snapshot identity and build context first.
Should local and CI use the same snapshot name?
Yes. Keep the name stable for the same page and state, and encode meaningful variants such as locale explicitly so each maps to the intended baseline.
What should I collect before asking for help?
Include both build links, project and branch context, snapshot names, variant and viewport settings, and the relevant test setup for data and capture readiness. Those details distinguish baseline selection from rendering differences.
