jest-image-snapshot "Expected image to match or be a close match" in CI

jest-image-snapshot compared the captured PNG against the stored baseline in __image_snapshots__ and the difference exceeded the configured threshold. By default that threshold is 0, so any single differing pixel fails. It reports the differing pixel count and percentage and writes a diff into __diff_output__.

What this error means

A toMatchImageSnapshot() assertion fails with "Expected image to match or be a close match to snapshot but was NNN% different from snapshot." A diff PNG appears under __image_snapshots__/__diff_output__.

jest-image-snapshot

  Expected image to match or be a close match to snapshot but was 3.21% different from snapshot
  (12043 differing pixels).
  See diff for details:
  __image_snapshots__/__diff_output__/homepage-diff.png

Common causes

Default threshold of zero on noisy renderers

Without a failureThreshold, one differing pixel from anti-aliasing fails the test, and CI renderers rarely match a developer machine to the pixel.

A real visual change without a baseline update

The component changed and the committed snapshot is stale. The diff output shows the actual delta.

How to fix it

Configure a percentage failure threshold

Allow a small percentage delta so rendering noise passes while real changes still fail. Pair failureThreshold with failureThresholdType: 'percent' so the value is size-independent.

test/home.test.js

expect(image).toMatchImageSnapshot({
  failureThreshold: 0.02,
  failureThresholdType: 'percent',
});

Regenerate baselines in the CI environment

If the diff is only rendering noise, update snapshots inside the same container CI uses and commit them.

Terminal

jest --ci --updateSnapshot

How to prevent it

Set a failureThreshold with failureThresholdType: 'percent'.
Generate baselines in the same container image as CI.
Commit __image_snapshots__ and review diffs in __diff_output__.