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
- 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 @emerson-eps/cypress-image-snapshot

npm

npm install --save-dev @emerson-eps/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 '@emerson-eps/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 '@emerson-eps/cypress-image-snapshot'

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": {
// ...
},
"include": ["@emerson-eps/cypress-image-snapshot"]
}
`

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

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

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

#### Options

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'],
})
`

New options have been implemented to make the function recursive and to retry the snapshots:

`ts
cy.matchImageSnapshot({
// Time it takes for the snapshot command to time out if the snapshot is not correct
timeout: 5000,

//Sets a delay between recursive snapshots
delayBetweenTries: 1000,
})
`

$3

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

$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 10.x, 11.x and 12.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 @simonsmith/cypress-image-snapshot`

This is a rewrite of the plugin from Simon Smith.