What is cypress-image-snapshot?
The cypress-image-snapshot package is a plugin for Cypress that allows you to take and compare screenshots for visual regression testing. It helps ensure that your web application's UI does not change unexpectedly.
What are cypress-image-snapshot's main functionalities?
Snapshot Testing
This feature allows you to take a snapshot of the current state of a web page and compare it to a baseline image. If the images do not match, the test will fail.
cy.visit('http://example.com');
cy.matchImageSnapshot();
Custom Snapshot Names
You can specify a custom name for your snapshot, which is useful for organizing and identifying different snapshots.
cy.visit('http://example.com');
cy.matchImageSnapshot('customSnapshotName');
Snapshot Options
This feature allows you to customize the snapshot comparison with various options such as failure thresholds, custom diff configurations, and capture modes.
cy.visit('http://example.com');
cy.matchImageSnapshot({
failureThreshold: 0.03,
failureThresholdType: 'percent',
customDiffConfig: { threshold: 0.1 },
capture: 'viewport'
});
Other packages similar to cypress-image-snapshot
jest-image-snapshot
jest-image-snapshot is a Jest matcher for image comparisons. It is similar to cypress-image-snapshot but is designed to work with Jest, a popular JavaScript testing framework. It provides similar functionality for visual regression testing but is used in a different testing environment.
puppeteer-screenshot-tester
puppeteer-screenshot-tester is a package that allows you to take screenshots with Puppeteer and compare them for visual regression testing. It is similar to cypress-image-snapshot but uses Puppeteer, a headless browser automation tool, instead of Cypress.
webdriver-image-comparison
webdriver-image-comparison is a package for visual regression testing with WebDriver. It allows you to take and compare screenshots in WebDriver-based tests. It is similar to cypress-image-snapshot but is designed for use with WebDriver.
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. :see_no_evil:
Installation
Install from npm
npm install 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(on);
addMatchImageSnapshotCommand();
addMatchImageSnapshotCommand(commandName);
addMatchImageSnapshotCommand(options);
addMatchImageSnapshotCommand(commandName, options);
.matchImageSnapshot();
.matchImageSnapshot(name);
.matchImageSnapshot(options);
.matchImageSnapshot(name, options);
cy.matchImageSnapshot();
cy.matchImageSnapshot(name);
cy.matchImageSnapshot(options);
cy.matchImageSnapshot(name, options);
Usage
describe('Login', () => {
it('should be publicly accessible', () => {
cy.visit('/login');
cy.matchImageSnapshot();
cy.matchImageSnapshot('login');
cy.matchImageSnapshot(options);
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,
failureThresholdType: 'percent',
customDiffConfig: { threshold: 0.1 },
capture: 'viewport',
});
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
--config updateSnapshots=true
to update the snapshots.