cypress-plugin-snapshots

Plugin for snapshot tests in Cypress.io.
Temporary repository, until main repository updates Cypress peer dependency version to ^7.5.0

Installation

npm i cypress-plugin-snapshots -S

Usage for text snapshots

1describe('data test', () => {
2  it('toMatchSnapshot - JSON', () => {
3    return cy.request('data.json')
4      .its('body')
5      .toMatchSnapshot();
6  });
7
8  it('toMatchSnapshot - JSON with options', () => {
9    return cy.request('data.json')
10      .its('body')
11      .toMatchSnapshot({
12        ignoreExtraFields: true,
13      });
14  });
15
16  it('toMatchSnapshot - HTML', () => {
17    cy.visit('page.html')
18      .then(() => {
19        cy.get('div').toMatchSnapshot();
20      });
21  });
22});

You can pass the following options to toMatchSnapshot to override default behavior.

1{
2  "ignoreExtraFields": false,         // Ignore fields that are not in snapshot
3  "ignoreExtraArrayItems": false,     // Ignore if there are extra array items in result
4  "normalizeJson": true,              // Alphabetically sort keys in JSON
5  "replace": {                        // Replace `${key}` in snapshot with `value`.
6    "key": "value",
7  }
8}

replace Use replace with caution. Tests should be deterministic. It's often a better solution to influence your test result instead of your snapshot (by mocking data for example).

Usage for image snapshots

1it('toMatchImageSnapshot - element', () => {
2  cy.visit('/static/stub.html')
3    .then(() => {
4      cy.get('[data-test=test]')
5        .toMatchImageSnapshot();
6    });
7});
8
9it('toMatchImageSnapshot - whole page', () => {
10  cy.visit('/static/stub.html')
11    .then(() => {
12      cy.document()
13        .toMatchImageSnapshot();
14    });
15});

You can pass the following options to toMatchImageSnapshot to override default behavior.

1{
2  "imageConfig": {
3    "createDiffImage": true,                // Should a "diff image" be created, can be disabled for performance
4    "threshold": 0.01,                      // Amount in pixels or percentage before snapshot image is invalid
5    "thresholdType": "percent",             // Can be either "pixel" or "percent"
6  },
7  "name": "custom image name",            // Naming resulting image file with a custom name rather than concatenating test titles
8  "separator": "custom image separator",  // Naming resulting image file with a custom separator rather than using the default ` #`
9}

You can also use any option from the cypress.screenshot arguments list.

For example:

1cy.get('.element')
2  .toMatchImageSnapshot({
3    clip: { x: 0, y: 0, width: 100, height: 100 },
4  });

Configure Cypress.io

Add this to your cypress.json configuration file:

1"ignoreTestFiles": [
2  "**/__snapshots__/*",
3  "**/__image_snapshots__/*"
4]

Plugin

Find your cypress/plugins/index.js file and change it to look like this:

1const { initPlugin } = require('cypress-plugin-snapshots/plugin');
2
3module.exports = (on, config) => {
4  initPlugin(on, config);
5  return config;
6};

Command

Find your cypress/support/index.js file and add the following line:

1import 'cypress-plugin-snapshots/commands';

Make changes to default configuration

You can customize the configuration in the cypress.json file in the root of your Cypress project.

Add the configuration below to your cypress.json file to make changes to the default values.

1"env": {
2  "cypress-plugin-snapshots": {
3    "autoCleanUp": false,            // Automatically remove snapshots that are not used by test
4    "autopassNewSnapshots": true,    // Automatically save & pass new/non-existing snapshots
5    "diffLines": 3,                  // How many lines to include in the diff modal
6    "excludeFields": [],             // Array of fieldnames that should be excluded from snapshot
7    "ignoreExtraArrayItems": false,  // Ignore if there are extra array items in result
8    "ignoreExtraFields": false,      // Ignore extra fields that are not in `snapshot`
9    "normalizeJson": true,           // Alphabetically sort keys in JSON
10    "prettier": true,                // Enable `prettier` for formatting HTML before comparison
11    "imageConfig": {
12      "createDiffImage": true,       // Should a "diff image" be created, can be disabled for performance
13      "resizeDevicePixelRatio": true,// Resize image to base resolution when Cypress is running on high DPI screen, `cypress run` always runs on base resolution
14      "threshold": 0.01,             // Amount in pixels or percentage before snapshot image is invalid
15      "thresholdType": "percent"     // Can be either "pixels" or "percent"
16    },
17    "screenshotConfig": {            // See https://docs.cypress.io/api/commands/screenshot.html#Arguments
18      "blackout": [],
19      "capture": "fullPage",
20      "clip": null,
21      "disableTimersAndAnimations": true,
22      "log": false,
23      "scale": false,
24      "timeout": 30000
25    },
26    "serverEnabled": true,           // Enable "update snapshot" server and button in diff modal
27    "serverHost": "localhost",       // Hostname for "update snapshot server"
28    "serverPort": 2121,              // Port number for  "update snapshot server"
29    "updateSnapshots": false,        // Automatically update snapshots, useful if you have lots of changes
30    "backgroundBlend": "difference"  // background-blend-mode for diff image, useful to switch to "overlay"
31  }
32}

Caveats :warning:

There is currently an issue when running "All Tests" in Cypress with this plugin. You can follow the progress on the issue here and here. When running "All Tests" any tests that utilize cypress-plugin-snapshots will throw an error.

Roadmap

Below is a list of functionality that is under consideration for implementing in a next version.

• Fix handling of "update snapshot" button that contains a replacable field
• Disable "update snapshots" server in headless mode
• Add more unit tests
• Add JSDoc documentation
• Improve TypeScript bindings

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style.

License

This plugin is released under the MIT license.