{"id":26660120,"url":"https://github.com/frsource/cypress-plugin-visual-regression-diff","last_synced_at":"2025-04-11T15:11:32.853Z","repository":{"id":37885846,"uuid":"420815554","full_name":"FRSOURCE/cypress-plugin-visual-regression-diff","owner":"FRSOURCE","description":"Perform visual regression test with a nice GUI as help. 💅 Only for Cypress!","archived":false,"fork":false,"pushed_at":"2024-04-30T01:09:02.000Z","size":20705,"stargazers_count":155,"open_issues_count":25,"forks_count":21,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-01T11:06:14.384Z","etag":null,"topics":["cypress","cypress-plugin","image-comparison","image-diff","image-snapshot","testing","visual-diff","visual-regression-testing"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FRSOURCE.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["FRSOURCE"],"patreon":"frsource","custom":["https://www.buymeacoffee.com/FRSOURCE"]}},"created_at":"2021-10-24T23:00:01.000Z","updated_at":"2024-05-03T18:03:07.724Z","dependencies_parsed_at":"2023-11-09T02:39:19.131Z","dependency_job_id":"946e1d5b-7319-494c-aa18-646a33626eb2","html_url":"https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff","commit_stats":{"total_commits":308,"total_committers":11,"mean_commits":28.0,"dds":0.6428571428571428,"last_synced_commit":"e48a9dbf444fa1669a129c0142b2f3cf875ec9d2"},"previous_names":[],"tags_count":126,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Fcypress-plugin-visual-regression-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Fcypress-plugin-visual-regression-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Fcypress-plugin-visual-regression-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FRSOURCE%2Fcypress-plugin-visual-regression-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FRSOURCE","download_url":"https://codeload.github.com/FRSOURCE/cypress-plugin-visual-regression-diff/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248429112,"owners_count":21101783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cypress","cypress-plugin","image-comparison","image-diff","image-snapshot","testing","visual-diff","visual-regression-testing"],"created_at":"2025-03-25T11:18:57.355Z","updated_at":"2025-04-11T15:11:32.830Z","avatar_url":"https://github.com/FRSOURCE.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@frsource/cypress-plugin-visual-regression-diff\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/v/@frsource/cypress-plugin-visual-regression-diff.svg\" alt=\"NPM version badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@frsource/cypress-plugin-visual-regression-diff\"\u003e\n    \u003cimg src=\"https://img.shields.io/npm/dt/@frsource/cypress-plugin-visual-regression-diff.svg\" alt=\"NPM total downloads badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codeclimate.com/github/FRSOURCE/cypress-plugin-visual-regression-diff/maintainability\"\u003e\n    \u003cimg src=\"https://api.codeclimate.com/v1/badges/b4f9a6e7b071771dd82f/maintainability.svg\" alt=\"CodeClimate maintainability badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://codeclimate.com/github/FRSOURCE/cypress-plugin-visual-regression-diff/test_coverage\"\u003e\n    \u003cimg src=\"https://api.codeclimate.com/v1/badges/b4f9a6e7b071771dd82f/test_coverage\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/semantic-release/semantic-release\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg\" alt=\"semantic-relase badge\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/FRSOURCE/cypress-plugin-visual-regression-diff.svg\" alt=\"license MIT badge\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/blob/main/assets/logo.svg\" alt=\"Cypress Plugin Visual Regression Diff logo\" height=\"120px\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePlugin for Cypress - Visual Regression Diff\u003c/h1\u003e\n\u003cp align=\"center\"\u003ePerform visual regression test with a nice GUI as help. 💅 \u003ci\u003eOnly\u0026nbsp;for\u0026nbsp;Cypress!\u003c/i\u003e Both e2e and component-testing compatible 💪\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n  ·\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n  ·\n  \u003ca href=\"#faq\"\u003eFAQ\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/issues\"\u003eFile an Issue\u003c/a\u003e\n  ·\n  \u003ca href=\"https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/discussions\"\u003eHave a question or an idea?\u003c/a\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003ci\u003ePlugin for visual regression testing that provides smooth experience:\n    \u003cbr\u003eSpecify threshold below which the test will fail.\n    \u003cbr\u003eQuickly preview old \u0026amp; new screenshot directly in the Cypress UI.\n    \u003cbr\u003eFind visual changes using images diff.\n    \u003cbr\u003ePublished as treeshakeable bundles, separate for JS ES5 or modern bundlers thanks to \u003ca href=\"https://www.npmjs.com/package/microbundle\"\u003emicrobundle\u003c/a\u003e.\n    \u003cbr\u003eWorking with every bundler (tested on webpack, vite, rollup),\n    \u003cbr\u003eProvides proper typings as is written completely in \u003ca href=\"https://www.typescriptlang.org\"\u003etypescript\u003c/a\u003e.\u003c/i\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n![frsource-visual-testing-example](https://user-images.githubusercontent.com/10456649/191988386-2be2ea14-7b7a-4048-a14e-0cad8d21e214.gif)\n\n## Getting started\n\n### Installation\n\nYou can install this library using your favorite package manager:\n\n```bash\n# npm\nnpm install --save-dev @frsource/cypress-plugin-visual-regression-diff\n\n# yarn\nyarn add -D @frsource/cypress-plugin-visual-regression-diff\n\n# pnpm\npnpm add -D @frsource/cypress-plugin-visual-regression-diff\n```\n\nNext, you need to import the library:\n\n- first, in your support file (located by default in `cypress/support/index.js`):\n\n```ts\n// typescript / ES6\nimport \"@frsource/cypress-plugin-visual-regression-diff\";\n\n// javascript\nrequire(\"@frsource/cypress-plugin-visual-regression-diff\");\n```\n\n- secondly:\n  - (for Cypress 10.0+) in `cypress.config.js` (or `cypress.config.ts`):\n\n```ts\n// typescript / ES6\nimport { defineConfig } from \"cypress\";\nimport { initPlugin } from \"@frsource/cypress-plugin-visual-regression-diff/plugins\";\n\nexport default defineConfig({\n  // initPlugin must be called in the section where it is used: e2e or component\n  e2e: {\n    setupNodeEvents(on, config) {\n      initPlugin(on, config);\n    },\n  },\n  component: {\n    setupNodeEvents(on, config) {\n      initPlugin(on, config);\n    },\n  },\n});\n```\n\n- (for Cypress \u003c10.0) in your plugins file (located by default in `cypress/plugins/index.js`):\n\n```ts\n// typescript / ES6\nimport { initPlugin } from \"@frsource/cypress-plugin-visual-regression-diff/plugins\";\n\nexport default function (\n  on: Cypress.PluginEvents,\n  config: Cypress.PluginConfigOptions\n) {\n  initPlugin(on, config);\n\n  return config;\n}\n\n// javascript\nconst {\n  initPlugin,\n} = require(\"@frsource/cypress-plugin-visual-regression-diff/plugins\");\n\nmodule.exports = function (on, config) {\n  initPlugin(on, config);\n\n  return config;\n};\n```\n\nThat's it - now let's see how to use the library in [usage section](#usage).\n\n## Usage\n\nOnce installed, the library might be used by writing in your test:\n\n```ts\ncy.get(\".an-element-of-your-choice\").matchImage();\n```\n\nOr, if you would like to make a screenshot of whole document:\n\n```ts\ncy.matchImage();\n```\n\n`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.\n\n## Example\n\nStill got troubles with installation? Have a look at [examples directory of this repo](./examples) to see how this plugin can be used in e2e or component-testing Cypress environment within your project.\n\n## Automatic clean up of unused images\n\nIt's useful to remove screenshots generated by the visual regression plugin that are not used by any test anymore.\nEnable this feature via env variable and enjoy freed up storage space 🚀:\n\n```bash\nnpx cypress run --env \"pluginVisualRegressionCleanupUnusedImages=true\"\n```\n\n## Configuration\n\nConfigure the plugin:\n\n- by passing in configuration as an argument to `matchImage` command:\n\n```ts\ncy.matchImage({\n  // screenshot configuration, passed directly to the the Cypress screenshot method: https://docs.cypress.io/api/cypress-api/screenshot-api#Arguments\n  // default: { }\n  screenshotConfig: {\n    blackout: ['.element-to-be-blackouted']\n  },\n  // pixelmatch options, see: https://www.npmjs.com/package/pixelmatch#pixelmatchimg1-img2-output-width-height-options\n  // default: { includeAA: true }\n  diffConfig: {\n    threshold: 0.01,\n  },\n  // whether to create missing baseline images automatically\n  // default: true\n  createMissingImages: false,\n  // whether to update images automatically, without making a diff - useful for CI\n  // default: false\n  updateImages: true,\n  // directory path in which screenshot images will be stored\n  // relative path are resolved against project root\n  // absolute paths (both on unix and windows OS) supported\n  // 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\n  // There are one special variable available to be used in the path:\n  // - {spec_path} - relative path leading from project root to the current spec file directory (e.g. `/src/components/my-tested-component`)\n  // default: '{spec_path}/__image_snapshots__'\n  imagesPath: 'this-might-be-your-custom/maybe-nested-directory',\n  // maximum threshold above which the test should fail\n  // default: 0.01\n  maxDiffThreshold: 0.1,\n  // forces scale factor to be set as value \"1\"\n  // helps with screenshots being scaled 2x on high-density screens like Mac Retina\n  // default: true\n  forceDeviceScaleFactor: false,\n  // title used for naming the image file\n  // default: Cypress.currentTest.titlePath (your test title)\n  title: `${Cypress.currentTest.titlePath.join(' ')} (${Cypress.browser.displayName})`,\n  // pass a path to custom image that should be used for comparison\n  // instead of checking against the image from previous run\n  // default: undefined\n  matchAgainstPath: '/path/to/reference-image.png'\n})\n```\n\n- via [global env configuration](https://docs.cypress.io/guides/guides/environment-variables#Setting). Environment variable names are the same as keys of the configuration object above, but with added `pluginVisualRegression` prefix, e.g.:\n\n```bash\nnpx cypress run --env \"pluginVisualRegressionUpdateImages=true,pluginVisualRegressionDiffConfig={\\\"threshold\\\":0.01}\"\n```\n\n```ts\n// cypress.config.ts\nimport { defineConfig } from \"cypress\";\n\nexport default defineConfig({\n  env: {\n    pluginVisualRegressionUpdateImages: true,\n    pluginVisualRegressionDiffConfig: { threshold: 0.01 },\n  },\n});\n```\n\n```json\n// cypress.env.json (https://docs.cypress.io/guides/guides/environment-variables#Option-2-cypress-env-json)\n{\n  \"pluginVisualRegressionUpdateImages\": true,\n  \"pluginVisualRegressionDiffConfig\": { \"threshold\": 0.01 }\n}\n```\n\nFor more ways of setting environment variables [take a look here](https://docs.cypress.io/guides/guides/environment-variables#Setting).\n\n## FAQ\n\n\u003cdetails\u003e\u003csummary\u003eWhy screenshots doesn't conform to the `viewport` set in my Cypress configuration?\u003c/summary\u003e\n\nScreenshots in Cypress do not scale to the viewport size by default. You can change this behavior:\n\n- globally, by changing default screenshot configuration: \u003ccode\u003eCypress.Screenshot.defaults({ capture: 'viewport' });\u003c/code\u003e\n- locally, by passing screenshot configuration directly to the \u003ccode\u003e.matchImage\u003c/code\u003e command: \u003ccode\u003ecy.matchImage({ screenshotConfig: { capture: 'viewport' } });\u003c/code\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003eI've upgraded version of this plugin and all on my baseline images has been automatically updated. Why?\u003c/summary\u003e\n\nSometimes 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!\n\n\u003c/details\u003e\n\n## Questions\n\nDon’t hesitate to ask a question directly on the [discussions board](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/discussions)!\n\n## Changelog\n\nChanges for every release are documented in the [release notes](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/releases) and [CHANGELOG files of every package](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/tree/main/packages).\n\n## License\n\n[MIT](https://opensource.org/licenses/MIT)\n\nCopyright (c) 2021-present, Jakub FRS Freisler, [FRSOURCE](https://www.frsource.org/)\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://www.frsource.org/\" title=\"Click to visit FRSOURCE page!\"\u003e\n\u003cimg src=\"https://www.frsource.org/logo.jpg\" alt=\"FRSOURCE logo\" height=\"60px\"/\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n","funding_links":["https://github.com/sponsors/FRSOURCE","https://patreon.com/frsource","https://www.buymeacoffee.com/FRSOURCE"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrsource%2Fcypress-plugin-visual-regression-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffrsource%2Fcypress-plugin-visual-regression-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffrsource%2Fcypress-plugin-visual-regression-diff/lists"}