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

``bash


yarn

yarn add --dev @simonsmith/cypress-image-snapshot

npm

npm install --save-dev @simonsmith/cypress-image-snapshot
`

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

`ts
// cypress.config.ts

import {defineConfig} from 'cypress'
import {addMatchImageSnapshotPlugin} from '@simonsmith/cypress-image-snapshot/plugin'

export default defineConfig({
e2e: {
setupNodeEvents(on) {
addMatchImageSnapshotPlugin(on)
},
},
})
`

Add the command to your relevant support file:

`ts
// cypress/support/e2e.ts

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

addMatchImageSnapshotCommand()

// can also add any default options to be used
// by all instances of matchImageSnapshot
addMatchImageSnapshotCommand({
failureThreshold: 0.2,
})
`

$3

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

$3

`ts
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');

// snapshot will be created inside some/dir
cy.matchImageSnapshot('some/dir/image')

// options object passed in
cy.matchImageSnapshot({
failureThreshold: 0.4
blur: 10
});

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

$3

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

- jest-image-snapshot
- Cypress screenshot

`ts
cy.matchImageSnapshot({
// options for jest-image-snapshot
failureThreshold: 0.2,
comparisonMethod: 'ssim',

// options for Cypress.screenshot()
capture: 'viewport',
blackout: ['.some-element'],
})
`

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

`ts
{
snapFilenameExtension: '.snap',
diffFilenameExtension: '.diff',
}
`

`ts
// will create a snap called some-name.custom-snap-name.png
cy.matchImageSnapshot('some-name', {
snapFilenameExtension: '.custom-snap-name',
})

// will create a snap called some-name.png
cy.matchImageSnapshot('some-name', {
snapFilenameExtension: '',
})

// will create a diff called some-name.wrong.png when a test fails
cy.matchImageSnapshot('some-name', {
diffFilenameExtension: '.wrong',
})
`

#### 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:

`ts
addMatchImageSnapshotCommand({
e2eSpecDir: 'cypress/e2e/', // the default value
})
`

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

$3

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

$3

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.

$3

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 /cypress/snapshots and if so diff against that snapshot.
3. If there is a resulting diff, save it to /cypress/snapshots/__diff_output__.

Requirements

Tested on Cypress 13.x and 14.x

Cypress must be installed as a peer dependency

Contributing

$3

- 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

$3

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.