FRSOURCE/cypress-plugin-visual-regression-diffPublic

NotificationsYou must be signed in to change notification settings
Fork21
Star175

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

License

MIT license

175 stars 21 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 387 Commits
.github/workflows		.github/workflows
assets		assets
examples		examples
packages/cypress-plugin-visual-regression-diff		packages/cypress-plugin-visual-regression-diff
.editorconfig		.editorconfig
.gitignore		.gitignore
.nvmrc		.nvmrc
.release-please-manifest.json		.release-please-manifest.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
eslint.config.mjs		eslint.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
release-please-config.json		release-please-config.json
renovate.json		renovate.json

Repository files navigation

Plugin for Cypress - Visual Regression Diff

Perform visual regression test with a nice GUI as help. 💅Only for Cypress! Both e2e and component-testing compatible 💪

Getting Started ·Usage ·FAQ ·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 tomicrobundle.
Working with every bundler (tested on webpack, vite, rollup),
Provides proper typings as is written completely intypescript.

Getting started

Installation

You can install this library using your favorite package manager:

# npmnpm install --save-dev @frsource/cypress-plugin-visual-regression-diff# yarnyarn add -D @frsource/cypress-plugin-visual-regression-diff# pnpmpnpm add -D @frsource/cypress-plugin-visual-regression-diff

Next, you need to import the library:

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

// typescript / ES6import"@frsource/cypress-plugin-visual-regression-diff";// javascriptrequire("@frsource/cypress-plugin-visual-regression-diff");

secondly:
- (for Cypress 10.0+) incypress.config.js (orcypress.config.ts):

// typescript / ES6import{defineConfig}from"cypress";import{initPlugin}from"@frsource/cypress-plugin-visual-regression-diff/plugins";exportdefaultdefineConfig({// initPlugin must be called in the section where it is used: e2e or componente2e:{setupNodeEvents(on,config){initPlugin(on,config);},},component:{setupNodeEvents(on,config){initPlugin(on,config);},},});

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

// typescript / ES6import{initPlugin}from"@frsource/cypress-plugin-visual-regression-diff/plugins";exportdefaultfunction(on:Cypress.PluginEvents,config:Cypress.PluginConfigOptions){initPlugin(on,config);returnconfig;}// javascriptconst{  initPlugin,}=require("@frsource/cypress-plugin-visual-regression-diff/plugins");module.exports=function(on,config){initPlugin(on,config);returnconfig;};

That's it - now let's see how to use the library inusage 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 atexamples 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 tomatchImage 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: truecreateMissingImages:false,// whether to update images automatically, without making a diff - useful for CI// default: falseupdateImages: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.01maxDiffThreshold: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: trueforceDeviceScaleFactor: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: undefinedmatchAgainstPath:'/path/to/reference-image.png'})

viaglobal env configuration. Environment variable names are the same as keys of the configuration object above, but with addedpluginVisualRegression prefix, e.g.:

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

// cypress.config.tsimport{defineConfig}from"cypress";exportdefaultdefineConfig({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 variablestake a look here.

FAQ

Why screenshots doesn't conform to the `viewport` set in my Cypress configuration?

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' } });

I've upgraded version of this plugin and all on my baseline images has been automatically updated. Why?

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!