Jest matcher for image comparisons using pixelmatch with all the goodness of Jest snapshots out of the box.

This project was heavily inspired by jest-image-snapshot.

Internally, it works around Jest's snapshot features by keeping track of snapshot changes using checksum of the serialized image, passing and failing the snapshot tests accordingly according to the image comparison. This means you get interactive update for failing snapshot tests, removal of obsolete snapshots out of the box.

Note that when update flag is not specified and the image comparison falls within the specified threshold, the library will not perform any update and pass the test using the previously stored checksum.

As jest has yet to expose any hooks for obsolete snapshots, this library monkey patches some functions in jest's snapshotState to perform necessary clean up of the image files.

1. Extend Jest's expect with toMatchImageSnapshot exposed by the library

const { toMatchImageSnapshot } = require('jest-image-snapshot');
expect.extend({ toMatchImageSnapshot });

2. Or use configureToMatchImageSnapshot to specify default configuration (refer to Optional Configuration below for details)

const { configureToMatchImageSnapshot } = require('jest-image-snapshot');
const toMatchImageSnapshot = configureToMatchImageSnapshot({
  customDiffConfig: { threshold: 0.1 },
  noColors: false,
  failureThresholdType: 'percent',
  failureThreshold: 0.01
});
expect.extend({ toMatchImageSnapshot });

2. Finally, use expect(...).toMatchImageSnapshot() in your tests

it('should match image snapshot', () => {
  // ...
  expect(img).toMatchImageSnapshot();
});

The following configuration can be passed as object to both configureToMatchImageSnapshot as default and expect(...).toMatchImageSnapshot as override for particular tests,

• customDiffConfig, options passed to pixelmatch. Default: { threshold: 0.01 }
• noColors, flag to disable chalk coloring. Default: false
• failureThresholdType, used in conjuction with failureThreshold, options are pixel (default) or percent
• failureThreshold, used in conjunction with failureThresholdType, for percent, it ranges from 0-1. Default: 0

The following configuration can be used in conjunction with configuration above for expect(...).toMatchImageSnapshot() only,

• name, custom name for the snapshot, as passed to https://facebook.github.io/jest/docs/en/expect.html#tomatchsnapshotoptionalstring