cypress-pixelmatch-regression

This plugin was inspired by cypress-visual-regression and cypress-visual-regression-resemble-js plugins.

The plugin uses pixelmatch to compare screenshots. Written in Typescript. Supports Typescript.

It was created to create the most precise visual regression test, to be run on the same environment and to track the minimal visual changes. If you want to run you visual regression on a different machines, consider using pixelThreshold option to avoid anti-aliasing problem (see "Add Command" section)

Getting Started

Install

1npm i cypress-pixelmatch-regression --save

Cypress Configuration

1import { defineConfig } from 'cypress';
2import { addPixelmatchRegressionPlugin } from 'cypress-pixelmatch-regression/plugin';
3
4export default defineConfig({
5  screenshotsFolder: './cypress/snapshots/actual',
6  video: false,
7  trashAssetsBeforeRuns: true,
8
9  env: {
10    pixelmatchPlugin: {
11      baseDir: './cypress/snapshots/base',
12      diffDir: './cypress/snapshots/diff',
13    },
14  },
15
16  e2e: {
17    setupNodeEvents(on, config) {
18      addPixelmatchRegressionPlugin(on, config);
19    },
20  },
21
22  component: {
23    setupNodeEvents(on, config) {
24      addPixelmatchRegressionPlugin(on, config);
25    },
26  },
27});

• screenshotsFolder is a directory where actual screenshots will be saved; cypress-pixelmatch-regression uses default cy.screenshot() command, and it saves them according to this parameter, it is required to run plugin
• baseDir is required, it is a directory where so-called baseline screenshots are kept
• diffDir is required, a directory with images containing rendered difference between actual and baseline screenshots
• alwaysGenerateDiff is optional, if true, difference files will be generated even if no difference found

Add Command

You can add the command (under cypress/support folder):

1import { addCompareSnapshotsCommand } from 'cypress-pixelmatch-regression/command';
2
3addCompareSnapshotsCommand();

The addCompareSnapshotsCommand() method takes an object as a parameter. It consists of standard cy.screenshot() arguments and also contains two additional parameters:

• errorThreshold is a number from 0 to 1, which represents sensitivity to relative number of different pixels between actual and base image. By default equals 0 (minimal difference will cause failing the test);
• pixelThreshold is the threshold value from the pixelmatch. Ranges from 0 to 1. The smaller the value, the more sensitive pixel-by-pixel comparison; may be useful in solving problem with anti-aliasing.

Pay your attention that sensitivity is maximal by default, you may need to configure it. The value for pixelThreshold 0.1 is used in the most libraries

Usage

1// use predefined options:
2cy.get('#your-component').compareSnapshots('screenshot-name');
3
4// with options in command:
5cy.get('#your-component').compareSnapshots('screenshot-name', {
6  errorThreshold: 0.1,
7  pixelThreshold: 0.2,
8  // ...options for cy.screenshot()
9});