README

Plugin for Cypress - Visual Regression Diff

Perform visual regression test with a nice GUI as help. 💅 Only for Cypress!

Getting Started · Usage · File an Issue · Have a question or an idea?

Plugin for visual regression testing that provides smooth experience:
Specify threshold below which the test will fail.
Quickly preview old & new screenshot directly in the Cypress UI.
Find visual changes using images diff.
Published as treeshakeable bundles, separate for JS ES5 or modern bundlers thanks to microbundle.
Working with every bundler (tested on webpack, vite, rollup),
Provides proper typings as is written completely in typescript.

https://user-images.githubusercontent.com/10456649/148709744-a23bc072-590a-4997-8ab8-252dc1b21791.mp4

Getting started

Installation

You can install this library using your favorite package manager:

# yarn
yarn add -D @frsource/cypress-plugin-visual-regression-diff

# npm
npm install --save-dev @frsource/cypress-plugin-visual-regression-diff

Next, you need to import the library:

first, in your support file (located by default in cypress/support/index.js):

// typescript
import '@frsource/cypress-plugin-visual-regression-diff/dist/support';

// javascript
require('@frsource/cypress-plugin-visual-regression-diff/dist/support');

secondly, in your plugins file (located by default in cypress/plugins/index.js):

// typescript
import { initPlugin } from '@frsource/cypress-plugin-visual-regression-diff/dist/plugins';

export default function (on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions) {
  initPlugin(on, config);

  return config;
};

// javascript
const { initPlugin } = require('@frsource/cypress-plugin-visual-regression-diff/dist/plugins');

module.exports = function (on, config) {
  initPlugin(on, config);

  return config;
}

That's it - now let's see how to use the library in usage section.

Usage

Once installed, the library might be used by writing in your test:

cy.get('.an-element-of-your-choice').matchImage();

Or, if you would like to make a screenshot of whole document:

cy.matchImage();

matchImage command will do a screenshot and compare it with image from a previous run. In case of regression the test will fail and you'll get a "Compare images" button to see what's a root of a problem.

Configuration

This plugin can be configured either:

directly, on a matcher level - by passing in plugin options as an argument to matchImage command, e.g.:

cy.matchImage({
  // screenshot configuration, passed directly to the the Cypress screenshot method: https://docs.cypress.io/api/cypress-api/screenshot-api#Arguments
  // default: { }
  screenshotConfig: {
    blackout: ['.element-to-be-blackouted']
  },
  // pixelmatch options, see: https://www.npmjs.com/package/pixelmatch#pixelmatchimg1-img2-output-width-height-options
  // default: { includeAA: true }
  diffConfig: {
    threshold: 0.01,
  },
  // whether to update images automatically, without making a diff - useful for CI
  // default: false
  updateImages: true,
  // directory path in which screenshot images will be stored
  // image visualiser will normalise path separators depending on OS it's being run within, so always use / for nested paths
  // default: '__image_snapshots__'
  imagesDir: 'this-might-be-your-custom/maybe-nested-directory',
  // maximum threshold above which the test should fail
  // default: 0.01
  maxDiffThreshold: 0.1
})

via global env configuration. All of the environment variable names are the same as keys of the configuration options passed to matchImage method, but with added pluginVisualRegression prefix, e.g.:

npx cypress run --env "pluginVisualRegressionUpdateImages=true" --env 'pluginVisualRegressionDiffConfig={"threshold":0.01}'

// cypress.json
{
  "env": {
    "pluginVisualRegressionUpdateImages": true,
    "pluginVisualRegressionDiffConfig": { "threshold": 0.01 }
  }
}

// cypress.env.json (https://docs.cypress.io/guides/guides/environment-variables#Option-2-cypress-env-json)
{
  "pluginVisualRegressionUpdateImages": true,
  "pluginVisualRegressionDiffConfig": { "threshold": 0.01 }
}

For more ways of setting environment variables take a look here.

Questions

Don’t hesitate to ask a question directly on the discussions board!

Changelog

Changes for every release are documented in the release notes and CHANGELOG files of every package.

License

MIT

Usage no npm install needed!