@frsource/cypress-plugin-visual-regression-diff v3.3.10
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
(orcypress.config.ts
):
- (for Cypress 10.0+) in
// 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 "See comparison" 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 environment within your project.
Automatic clean up of unused images
It's useful to remove screenshots generated by the visual regression plugin that are not used by any test anymore. Enable this feature via env variable and enjoy freed up storage space 🚀:
npx cypress run --env "pluginVisualRegressionCleanupUnusedImages=true"
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 create missing baseline images automatically
// default: true
createMissingImages: false,
// 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
// relative path are resolved against project root
// absolute paths (both on unix and windows OS) supported
// path separators will be normalised by the plugin depending on OS, you should always use / as path separator, e.g.: C:/my-directory/nested for windows-like drive notation
// There are one special variable available to be used in the path:
// - {spec_path} - relative path leading from project root to the current spec file directory (e.g. `/src/components/my-tested-component`)
// default: '{spec_path}/__image_snapshots__'
imagesPath: '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' } });
Sometimes we need to do a breaking change in image comparison or image generation algorithms. To provide you with the easiest upgrade path - the plugin updates your baseline images automatically. Just commit them to your repository after the plugin upgrade and you are good to go!
DIFF_IMAGES_VERSION
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
Copyright (c) 2021-present, Jakub FRS Freisler, FRSOURCE
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
3 years ago
3 years ago
3 years ago
3 years ago
3 years ago