Cypress Image Snapshot binds [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot)'s image diffing logic to [Cypress.io](https://cypress.io) commands.
npm install @emerson-eps/cypress-image-snapshotCypress 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
Install with your chosen package manager
``bashyarn
yarn add --dev @emerson-eps/cypress-image-snapshot
setupNodeEvents function:`ts
// cypress.config.tsimport {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.tsimport {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 projectEnsure 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.
`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 and if so diff against that snapshot.
3. If there is a resulting diff, save it to .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:openIn 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:runThe 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=falseIt'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.