Jest-screenshot NPM

jest-screenshot

A jest extension to deal with screenshots and all sorts of images. Inspired by the awesome jest-image-snapshot and providing a mostly compatible API with similar features. By utilizing native-image-diff instead of pixelmatch and node-libpng instead of pngjs the tests will run much faster than its competitor.

Please also refer to the Documentation.

jest-screenshot

Installation

Two steps are necessary in order to use this plugin:

Install the expect().toMatchImageSnapshot() extension. (Here)
Install the reporter. (Here)

Installing the expect extension

Integrate this plugin by calling setupJestScreenshot in the framework setup file:

import { setupJestScreenshot } from "jest-screenshot";

setupJestScreenshot();

Store the above code in a setup-framework.js file and specify it when configuring Jest:

"jest": {

    "setupTestFrameworkScriptFile": "<rootDir>/setup-framework.js"

}

TypeScript Tip: to enable jest matcher types for toMatchImageSnapshot(), use a *.ts for your setup file.

Installing the reporter

In order to generate the report, the reporter must be registered in the Jest configuration:

"jest": {

    "reporters": [
        "default",
        "jest-screenshot/reporter"
    ]

}

Configuring

By placing a file jest-screenshot.json in the root directory of your project with a configuration object you can configure it:

Parameter	type	default	Description
`detectAntialiasing`	boolean	`true`	Whether to attempt to detect antialiasing and ignore related changes when comparing both images. See documentation.
`colorThreshold`	number	`0.1`	A number in the range from `0` to `1` describing how sensitive the comparison of two pixels should be. See documentation.
`pixelThresholdAbsolute`	number	`undefined`	If specified, jest-screenshot will fail if more than the specified pixels are different from the snapshot.
`pixelThresholdRelative`	number	`0`	If specified, jest-screenshot will fail if more than the specified relative amount of pixels are different from the snapshot. When setting this to `0.5` for example, more than 50% of the pixels need to be different for the test to fail.
`snapshotsDir`	string	`__snapshots__`	If specified, will change the directory into which the snapshot images will be stored, relative to the unit test file.
`reportDir`	string	`jest-screenshot-report`	If specified, will change the directory into which the HTML report will be written, relative to the project's root directory.
`noReport`	boolean	`false`	Set this to `true` in order to completely disable the HTML report.

It's also possible to specify a key jestScreenshot in the package.json with the same interface.

All configuration options are optional.

If neither pixelThresholdAbsolute nor pixelThresholdRelative are specified, pixelThresholdRelative will be set to 0. Both can be specified together in order to make the test fail on both conditions.

Example

{
    "detectAntialiasing": false,
    "colorThreshold": 0,
    "pixelThresholdAbsolute": 150,
    "pixelThresholdRelative": 0.5
};

The above config will make the tests fail if more than 150 pixels in total changed or more than 50% of the pixels changed. It will detect any pixel as changed even if the color only differs minimally and antialiasing detection is disabled.

Usage

Take a look at the example project.

This library can be used to compare images with snapshots:

describe("My fancy image", () => {
    const myFancyImage = readFileSync("../my-fancy-image.png");

    it("looks as beautiful as always", () => {
        expect(myFancyImage).toMatchImageSnapshot();
    });
});

This is for example useful for integration tests with puppeteer:

describe("My fancy webpage", () => {
    const page = ...; // Setup puppeteer.

    it("looks as gorgeous as ever", async () => {
        expect(await page.screenshot()).toMatchImageSnapshot();
    });
});

It is possible to specify a custom path to store the snapshot at:

describe("My fancy image", () => {
    const myFancyImage = readFileSync("../my-fancy-image.png");

    it("looks as beautiful as always", () => {
        expect(myFancyImage).toMatchImageSnapshot({ path: "../../my-fancy-image.snap.png" });
    });
});

It is possible to import toMatchImageSnapshot() for custom assertions. As it requires configuration as second argument, config() function (which is responsible for reading configuration from jest-screenshot.json/package.json) is also exposed.

import {config, toMatchImageSnapshot} from 'jest-screenshot';

expect.extend({
  customMatcher(received, name) {
    const image = customGetImage(received); // i.e. via puppeteer, html2canvas etc
    const configuration = config(); // get existing config
    if(process.env.LOOSE_SCREENSHOTS_MATCH) {
        // loose mismatch threshold for specific environment setting
        configuration.pixelThresholdRelative = configuration.pixelThresholdRelative + 0.1
    }
    return toMatchImageSnapshot.call(this, image, configuration, {
        // build custom path for screenshot
        path: `/custom_file_path/${configuration.snapshotsDir}/custom_file_prefix_${name}.png`
    });
  }
});

Benchmark

This library is around 10x faster than jest-image-snapshot.

In the benchmark a whole unit test suite, including setup and teardown of the jest environment and 30 unit tests (10 matching, 10 not matching and 10 newly created) were measured. Writing of the report is also included.

Benchmark