@frsource/cypress-plugin-visual-regression-diff NP

frsource-visual-testing-example

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 / ES6
import '@frsource/cypress-plugin-visual-regression-diff';

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

secondly:
- (for Cypress 10.0+) in cypress.config.js (or cypress.config.ts):

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

export default defineConfig({
  // initPlugin must be called in the section where it is used: e2e or component
  e2e: {
    setupNodeEvents(on, config) {
      initPlugin(on, config);
    }
  },
  component: {
    setupNodeEvents(on, config) {
      initPlugin(on, config);
    }
  }
});

(for Cypress <10.0) in your plugins file (located by default in cypress/plugins/index.js):

// typescript / ES6
import { initPlugin } from '@frsource/cypress-plugin-visual-regression-diff/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/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.

Example

Still got troubles with installation? Have a look at example directory of this repo to see how this plugin can be used in e2e or component-testing Cypress within your project.

Configuration

Configure the plugin:

by passing in configuration as an argument to matchImage command:

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,
  // forces scale factor to be set as value "1" 
  // helps with screenshots being scaled 2x on high-density screens like Mac Retina
  // default: true
  forceDeviceScaleFactor: false,
  // title used for naming the image file
  // default: Cypress.currentTest.titlePath (your test title)
  title: `${Cypress.currentTest.titlePath.join(' ')} (${Cypress.browser.displayName})`
  // pass a path to custom image that should be used for comparison
  // instead of checking against the image from previous run
  // default: undefined
  matchAgainstPath: '/path/to/reference-image.png'
})

via global env configuration. Environment variable names are the same as keys of the configuration object above, but with added pluginVisualRegression prefix, e.g.:

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

// cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  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.

FAQ

Screenshots in Cypress do not scale to the viewport size by default. You can change this behavior:

globally, by changing default screenshot configuration: Cypress.Screenshot.defaults({ capture: 'viewport' });
locally, by passing screenshot configuration directly to the .matchImage command: cy.matchImage({ screenshotConfig: { capture: 'viewport' } });