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
  • Table of contents
  • Installation
    • Installing the expect extension
    • Installing the reporter
    • Configuring
      • Example
  • Usage
  • Benchmark
  • Reports
  • Contributing
  • Contributors

Two steps are necessary in order to use this plugin:

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

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.

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

"jest": {

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

}

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

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.

{
    "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.

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`
    });
  }
});

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.

The X axis displays the amount of executed suites per second.

In average:

• jest-screenshot took ~9 seconds for 30 tests and
• jest-image-snapshot took >100 seconds.

An HTML report with interactive tools for comparing the failed snapshots will be generated if any tests failed.

A demo can be found here.

They might look for example like this:

The report will be placed in a jest-screenshot-report directory in the project's root directory by default.

Yarn is used instead of npm, so make sure it is installed. npm install -g yarn.

Generally, it should be enough to just run:

make

which will install all node dependencies, compile typescript, execute all test, lint the sources and build the docs.

• Frederick Gnodtke