Cypress Image Snapshot

Cypress Image Snapshot binds jest-image-snapshot's image diffing logic to Cypress.io commands.

• Installation
  • TypeScript
• Usage
  • In your tests
  • Options
    • Snapshot paths
  • Updating snapshots
  • Preventing failures
  • Requiring snapshots to be present
• How it works
• Requirements
• Contributing
  • Setup
  • Working on the plugin
    • open
    • run
      • Note on environment variables
• Forked from jaredpalmer/cypress-image-snapshot

Installation

Install with your chosen package manager

1# yarn
2yarn add --dev @simonsmith/cypress-image-snapshot
3
4# npm
5npm install --save-dev @simonsmith/cypress-image-snapshot

Next, import the plugin function and add it to the setupNodeEvents function:

1// cypress.config.ts
2
3import {defineConfig} from 'cypress'
4import {addMatchImageSnapshotPlugin} from '@simonsmith/cypress-image-snapshot/plugin'
5
6export default defineConfig({
7  e2e: {
8    setupNodeEvents(on) {
9      addMatchImageSnapshotPlugin(on)
10    },
11  },
12})

Add the command to your relevant support file:

1// cypress/support/e2e.ts
2
3import {addMatchImageSnapshotCommand} from '@simonsmith/cypress-image-snapshot/command'
4
5addMatchImageSnapshotCommand()
6
7// can also add any default options to be used
8// by all instances of `matchImageSnapshot`
9addMatchImageSnapshotCommand({
10  failureThreshold: 0.2,
11})

TypeScript

TypeScript is supported so any reference to @types/cypress-image-snapshot can be removed from your project

Ensure that the types are included in your tsconfig.json

{
  "compilerOptions": {
    // ...
  },
  "types": ["@simonsmith/cypress-image-snapshot/types"]
}

Usage

In your tests

1describe('Login', () => {
2  it('should be publicly accessible', () => {
3    cy.visit('/login');
4
5    // snapshot name will be the test title
6    cy.matchImageSnapshot();
7
8    // snapshot name will be the name passed in
9    cy.matchImageSnapshot('login');
10
11    // snapshot will be created inside `some/dir`
12    cy.matchImageSnapshot('some/dir/image')
13
14    // options object passed in
15    cy.matchImageSnapshot({
16      failureThreshold: 0.4
17      blur: 10
18    });
19
20    // match element snapshot
21    cy.get('#login').matchImageSnapshot();
22  });
23});

Options

The options object combines jest-image-snapshot and Cypress screenshot configuration.

• jest-image-snapshot
• Cypress screenshot

1cy.matchImageSnapshot({
2  // options for jest-image-snapshot
3  failureThreshold: 0.2,
4  comparisonMethod: 'ssim',
5
6  // options for Cypress.screenshot()
7  capture: 'viewport',
8  blackout: ['.some-element'],
9})

It is also possible to configure the extensions given to snap and diff files generated by the plugin. The default options are:

1{
2  snapFilenameExtension: '.snap',
3  diffFilenameExtension: '.diff',
4}

1// will create a snap called `some-name.custom-snap-name.png`
2cy.matchImageSnapshot('some-name', {
3  snapFilenameExtension: '.custom-snap-name',
4})
5
6// will create a snap called `some-name.png`
7cy.matchImageSnapshot('some-name', {
8  snapFilenameExtension: '',
9})
10
11// will create a diff called `some-name.wrong.png` when a test fails
12cy.matchImageSnapshot('some-name', {
13  diffFilenameExtension: '.wrong',
14})

Snapshot paths

As of Cypress 10.0.0 a change was made to remove common ancestor paths of generated screenshots. This means that it is difficult to mimic the folder structure found in the cypress/e2e/ directory when creating the snapshots directory.

To workaround this, cypress-image-snapshot makes use of a e2eSpecDir option. Here's an example:

1addMatchImageSnapshotCommand({
2  e2eSpecDir: 'cypress/e2e/', // the default value
3})

Example output in a project:

cypress
├── e2e
│  ├── matchImageSnapshot.cy.ts
│  ├── nested
│  │  └── test
│  └── someOtherTest.cy.ts
├── snapshots
│  ├── matchImageSnapshot.cy.ts
│  │  ├── matches with just options.snap.png
│  │  ├── name and options.snap.png
│  │  ├── no arguments.snap.png
│  │  └── with custom name.snap.png
│  ├── nested
│  │  └── test
│  └── someOtherTest.cy.ts
│     └── some other test taking a snapshot.snap.png

Without the e2eSpecDir option the cypress/e2e/ directories would be repeated inside the snapshots directory. Set this option to whatever directory structure is inside the specPattern configuration value.

See more:

• https://github.com/cypress-io/cypress/issues/22159
• https://github.com/cypress-io/cypress/issues/24052

Updating snapshots

Run Cypress with --env updateSnapshots=true in order to update the base image files for all of your tests.

Preventing failures

By default tests will fail when a snapshot fails to match. Run Cypress with --env failOnSnapshotDiff=false in order to prevent test failures when an image diff does not pass.

Requiring snapshots to be present

Run Cypress with --env requireSnapshots=true in order to fail if snapshots are missing. This is useful in continuous integration where snapshots should be present in advance.

How it works

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__.

Requirements

Tested on Cypress 10.x, 11.x and 12.x

Cypress must be installed as a peer dependency

Contributing

Setup

• Clone the repository and install the yarn dependencies with yarn install
• Ensure that Docker is setup. This is necessary for generating/updating snapshots
• Using Volta is recommended for managing Node and Yarn versions. These are automatically picked up from the package.json
• Commits should be based on conventional-changelog

Working on the plugin

To make it easier to test whilst developing there are a few simple Cypress tests that validate the plugin. There are two ways to run these tests:

open

yarn test:open

In open mode the tests run in Electron and ignore any snapshot failures. This is due to the rendering differences on developer machines vs CI. Here there is also verbose output sent to the test runner console to aid debugging.

Note here that the yarn script above will re-build the plugin each time. This is necessary because the tests are run against the output in the dist directory to ensure parity between the built package on NPM.

Ensure that the command is run each time changes need to be tested in Cypress

run

• yarn docker:build
• yarn docker:run

The commands here ensure that the tests are run inside a Docker container that matches the CI machine. This allows images to be generated and matched correctly when running the tests in Github Actions.

Note on environment variables

It is necessary to have two environment variables defined by default before running the tests in Docker:

• CYPRESS_updateSnapshots=false
• CYPRESS_debugSnapshots=false

It's recommended that these are loaded into the shell with something like direnv

Then they can be overridden as needed:

CYPRESS_updateSnapshots=true yarn docker:run

Forked from jaredpalmer/cypress-image-snapshot

This is a rewrite of the original plugin as active development has ceased. Full credit goes to Jared Palmer.