mattbgold / cypress-image-snapshot

Catch visual regressions in Cypress

Cypress Image Snapshot

Cypress Image Snapshot binds jest-image-snapshot's image diffing logic to Cypress.io commands. The goal is to catch visual regressions during integration tests. Here's what it looks like when tests run with the Cypress GUI.

This then constructs/uploads an image diff for analysis.

Boom! Turns out you probably can't delete that intern's CSS from 6 months ago that somehow made its way to prod. 🙈

Installation

Install from npm

npm install --save-dev cypress-image-snapshot

then add the following in your project's <rootDir>/cypress/plugins/index.js:

const {
  addMatchImageSnapshotPlugin,
} = require('cypress-image-snapshot/plugin');

module.exports = on => {
  addMatchImageSnapshotPlugin(on);
};

and in <rootDir>/cypress/support/commands.js add:

import { addMatchImageSnapshotCommand } from 'cypress-image-snapshot/command';

addMatchImageSnapshotCommand(options);

Syntax

// addMatchImageSnapshotPlugin
addMatchImageSnapshotPlugin(on);

// addMatchImageSnapshotCommand
addMatchImageSnapshotCommand();
addMatchImageSnapshotCommand(commandName);
addMatchImageSnapshotCommand(options);
addMatchImageSnapshotCommand(commandName, options);

// matchImageSnapshot
.matchImageSnapshot();
.matchImageSnapshot(name);
.matchImageSnapshot(options);
.matchImageSnapshot(name, options);

// ---or---

cy.matchImageSnapshot();
cy.matchImageSnapshot(name);
cy.matchImageSnapshot(options);
cy.matchImageSnapshot(name, options);

Usage

describe('Login', () => {
  it('should be publicly accessible', () => {
    cy.visit('/login');

    // snapshot name will be the test title
    cy.matchImageSnapshot();

    // snapshot name will be the name passed in
    cy.matchImageSnapshot('login');

    // options object passed in
    cy.matchImageSnapshot(options);

    // match element snapshot
    cy.get('#login').matchImageSnapshot();
  });
});

Options

Any options for cy.screenshot() and jest-image-snapshot can be passed in the options argument to addMatchImageSnapshotCommand and cy.matchImageSnapshot(). The local options in cy.matchImageSnapshot() will overwrite the default options set in addMatchImageSnapshot.

For example, the default options we use in <rootDir>/cypress/support/commands.js are:

addMatchImageSnapshotCommand({
  failureThreshold: 0.03, // threshold for entire image
  failureThresholdType: 'percent', // percent of image or number of pixels
  customDiffConfig: { threshold: 0.1 }, // threshold for each pixel
  capture: 'viewport', // capture viewport in screenshot
});

How it works

We really enjoy the diffing workflow of jest-image-snapshot and wanted to have a similar workflow when using Cypress. Because of this, under the hood we use some of jest-image-snapshot's internals and simply bind them to Cypress's commands and plugins APIs.

The workflow of cy.matchImageSnapshot() when running Cypress is:

1. Take a screenshot with cy.screenshot() named according to the current test.
2. Check if a saved snapshot exists in <rootDir>/cypress/snapshots and if so diff against that snapshot.
3. If there is a resulting diff, save it to <rootDir>/cypress/snapshots/__diff_output__.
4. If the diff is intended, run Cypress again with --env updateSnapshots=true to update the snapshots.