Cypress Image Diff
Cypress Image Diff 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.
![Cypress Image Diff in action](https://user-images.githubusercontent.com/4060187/41942389-5a6705ae-796d-11e8-8003-fadbf7ccf43d.gif)
This then constructs/uploads an image diff for analysis.
![Cypress Image Diff Diff](https://user-images.githubusercontent.com/4060187/41942163-72c8c20a-796c-11e8-9149-c295341864d3.png)
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-diff
then add the following in your project's <rootDir>/cypress/plugins/index.js
:
const addCleanupDiffOutputCommand addMatchImageSnapshotPlugin = ; module { ;};
and in <rootDir>/cypress/support/commands.js
add:
; ;;
Syntax
// addMatchImageSnapshotPlugin; // addMatchImageSnapshotCommand;;;; // addCleanupDiffOutputCommand (WARNING: must be run __after__ `addMatchImageSnapshotCommand`);; // cleanupDiffOutput; // ---or--- cy; // matchImageSnapshot;;;; // ---or--- cy;cy;cy;cy;
Usage
;
Options
customSnapshotsDir
: Path to the directory that snapshot images will be written to, defaults to<rootDir>/cypress/snapshots
.customDiffDir
: Path to the directory that diff images will be written to, defaults to a sibling__diff_output__
directory alongside each snapshot.
Additionally, 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:
;
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:
- Take a screenshot with
cy.screenshot()
named according to the current test. - Check if a saved snapshot exists in
<rootDir>/cypress/snapshots
and if so diff against that snapshot. - If there is a resulting diff, save it to
<rootDir>/cypress/snapshots/__diff_output__
. - If the diff is intended, run Cypress again with
--env updateSnapshots=true
to update the snapshots.