{"id":13711819,"url":"https://github.com/cypress-visual-regression/cypress-visual-regression","last_synced_at":"2025-05-06T21:32:25.002Z","repository":{"id":38450180,"uuid":"139510268","full_name":"cypress-visual-regression/cypress-visual-regression","owner":"cypress-visual-regression","description":"Module for adding visual regression testing to Cypress","archived":false,"fork":false,"pushed_at":"2025-04-30T19:09:26.000Z","size":10142,"stargazers_count":653,"open_issues_count":6,"forks_count":84,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-30T21:09:13.687Z","etag":null,"topics":["cypress","cypress-plugin","image-diff","visual-regression","visual-regressions"],"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/cypress-visual-regression.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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":"mjhea0"}},"created_at":"2018-07-03T00:56:25.000Z","updated_at":"2025-04-09T11:42:02.000Z","dependencies_parsed_at":"2023-10-12T00:58:55.463Z","dependency_job_id":"4c2a13d8-c3f0-4f99-a991-795492245824","html_url":"https://github.com/cypress-visual-regression/cypress-visual-regression","commit_stats":{"total_commits":343,"total_committers":41,"mean_commits":8.365853658536585,"dds":0.760932944606414,"last_synced_commit":"359fea4053aab6e097af6ecf0cbb01dd61f81125"},"previous_names":["mjhea0/cypress-visual-regression"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-visual-regression%2Fcypress-visual-regression","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-visual-regression%2Fcypress-visual-regression/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-visual-regression%2Fcypress-visual-regression/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cypress-visual-regression%2Fcypress-visual-regression/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cypress-visual-regression","download_url":"https://codeload.github.com/cypress-visual-regression/cypress-visual-regression/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252427998,"owners_count":21746316,"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-diff","visual-regression","visual-regressions"],"created_at":"2024-08-02T23:01:11.969Z","updated_at":"2025-05-06T21:32:22.961Z","avatar_url":"https://github.com/cypress-visual-regression.png","language":"TypeScript","funding_links":["https://github.com/sponsors/mjhea0"],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Cypress Visual Regression\n\n[![npm](https://img.shields.io/npm/v/cypress-visual-regression)](https://www.npmjs.com/package/cypress-visual-regression)\n\n[![github actions](https://github.com/mjhea0/cypress-visual-regression/workflows/Continuous%20Integration/badge.svg)](https://github.com/mjhea0/cypress-visual-regression/actions)\n\nPlugin that adds powerful visual regression testing capabilities to [Cypress](https://www.cypress.io/):\n\n![example](./cypress-visual-regression.gif)\n\n## Installation\n\n```nodejs\nnpm install cypress-visual-regression\n```\n\n## Configuration\n\n### JavaScript\n\nConfigure the visual regression plugin and environment variables in your _cypress.config.js_ file like:\n\n```javascript\nconst { defineConfig } = require('cypress')\nconst { configureVisualRegression } = require('cypress-visual-regression')\n\nmodule.exports = defineConfig({\n  e2e: {\n    env: {\n      visualRegressionType: 'regression'\n    },\n    screenshotsFolder: './cypress/snapshots/actual',\n    setupNodeEvents(on, config) {\n      configureVisualRegression(on)\n    }\n  }\n})\n```\n\nPay attention to the `visualRegressionType` option. Use 'base' to generate baseline images, and 'regression' to compare current\nscreenshot to the base screenshot\n\nIn your support file _cypress/support/e2e.js_ add the following:\n\n```javascript\nconst { addCompareSnapshotCommand } = require('cypress-visual-regression/dist/command')\naddCompareSnapshotCommand()\n```\n\n### TypeScript\n\nIf you're using TypeScript, use files with a `.ts` extension, as follows:\n\n_cypress.config.ts_\n\n```typescript\nimport { defineConfig } from 'cypress'\nimport { configureVisualRegression } from 'cypress-visual-regression'\n\nexport default defineConfig({\n  e2e: {\n    env: {\n      visualRegressionType: 'regression'\n    },\n    screenshotsFolder: './cypress/snapshots/actual',\n    setupNodeEvents(on, config) {\n      configureVisualRegression(on)\n    }\n  }\n})\n```\n\n_cypress/support/e2e.ts_\n\n```typescript\nimport { addCompareSnapshotCommand } from 'cypress-visual-regression/dist/command'\naddCompareSnapshotCommand()\n```\n\n_cypress/tsconfig.json_\n\n```json:\n{\n  \"ts-node\": {\n    \"transpileOnly\": true,\n    \"compilerOptions\": {\n      \"module\": \"ES2015\"\n    }\n  }\n}\n```\n\nFor more info on how to use TypeScript with Cypress, please refer to [this document](https://docs.cypress.io/guides/tooling/typescript-support#Set-up-your-dev-environment).\n\n## Plugin options\n\nAll options can be configured within `visualRegression` prefix under `env` variable inside `cypress.config.js` file, like this:\n\n```javascript\nmodule.exports = defineConfig({\n  e2e: {\n    screenshotsFolder: './cypress/snapshots/actual',\n    env: {\n      visualRegressionType: 'regression',\n      visualRegressionBaseDirectory: 'cypress/snapshot/base',\n      visualRegressionDiffDirectory: 'cypress/snapshot/diff',\n      visualRegressionGenerateDiff: 'always',\n      visualRegressionFailSilently: true\n    }\n  }\n})\n```\n\n| Variable                      | Default                  | Description                                                                                                                                                  |\n| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| visualRegressionType          | /                        | Either 'regression' or 'base'. Base will override any existing base images with new screenshots. Regression will compare the base to the current screenshot. |\n| visualRegressionBaseDirectory | 'cypress/snapshots/base' | Path to the directory where the base snapshots will be stored.                                                                                               |\n| visualRegressionDiffDirectory | 'cypress/snapshots/diff' | Path to the directory where the generated image differences will be stored.                                                                                  |\n| visualRegressionGenerateDiff  | 'fail'                   | Either 'fail', 'never' or 'always'. Determines if and when image differences are generated.                                                                  |\n| visualRegressionFailSilently  | false                    | Used to decide if any error found in regression should be thrown or returned as part of the result.                                                          |\n\nTo override different default arguments/options on a global level pass them to the `addCompareSnapshotCommand()` command:\n\n- cypress screenshot [arguments](https://docs.cypress.io/api/cypress-api/screenshot-api.html#Arguments)\n- pixelmatch [options](https://github.com/mapbox/pixelmatch?tab=readme-ov-file#pixelmatchimg1-img2-output-width-height-options)\n- plugin configuration (errorThreshold, failSilently)\n\n```javascript\nconst { addCompareSnapshotCommand } = require('cypress-visual-regression/dist/command')\naddCompareSnapshotCommand({\n  capture: 'fullPage', // cypress screenshot option\n  errorThreshold: 0.5, // plugin threshold option\n  pixelmatchOptions: {\n    threshold: 0 // pixelmatch threshold option\n  }\n})\n```\n\n### How To Use\n\n### \u003e syntax\n\n```TypeScript\ncy.compareSnapshot(name)\ncy.compareSnapshot(name, errorThreshold)\ncy.compareSnapshot(name, options)\n```\n\n### \u003e arguments\n\n| Arguments      | Default | Description                                                                                                                  |\n| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| name           | /       | Represents the name of the base snapshot file that the actual screenshot will be compared with.                              |\n| errorThreshold | 0       | Threshold under which any image difference will be considered as failed test. Represented in percentages.                    |\n| options        | {}      | Used to provide additional cypress screenshot arguments, pixelmatch options, and `failSilently` and `errorThreshold` values. |\n\n### \u003e yields\n\n- `.compareSnapshot()` yields the Visual Regression Result object which contains the following info:\n\n| Result           | Type               | Description                                                                                                   |\n| ---------------- | ------------------ | ------------------------------------------------------------------------------------------------------------- |\n| error            | string (optional)  | Contains visual regression error message                                                                      |\n| images           | object             | Contains `base64` string of generated images for `actual`, `base` (optional) and `diff` (optional) images     |\n| baseGenerated    | boolean (optional) | Set to `true` if visual regression plugin was run for base generation (`visualRegressionType` set to 'base')  |\n| mismatchedPixels | number (optional)  | Represents the number of total mismatched pixels during visual comparison. Set if difference were discovered  |\n| percentage       | number (optional)  | Represents the percentage of the difference between the images in decimals. Set if difference were discovered |\n\n### \u003e examples\n\n```TypeScript\ncy.compareSnapshot('homePage') // will compare actual screenshot to current and fail if there's any difference in the images\n\ncy.get('h1').compareSnapshot('homePage', 0.2) // will compare only the image of h1 element and fail only if the percentage of pixels that are different is bigger than 0.2 (20% difference)\n\ncy.compareSnapshot('homePage', {errorThreshold: 1, failSilently: true}).then(comparisonResults =\u003e {\n  console.log(comparisonResults.mismatchedPixels) // will print the number of mismatched pixels\n  console.log(comparisonResults.percentage) // will print the percentage (in decimals) of mismatched pixels\n  console.log(comparisonResults.error) // will print the visual regression error message (if any)\n})\n```\n\n\u003e Looking for more examples? See [cypress/e2e/main.cy.ts](https://github.com/cypress-visual-regression/cypress-visual-regression/blob/master/cypress/e2e/main.cy.ts).\n\n## Tips \u0026 Tricks\n\n### Ignore some elements\n\nFollowing function creates a command that allows you to hide elements of the page based on their className:\n\n```ts\n/**\n * To be called after you setup the command, in order to add a\n * hook that does stuff before the command is triggered\n */\nexport function beforeCompareSnapshots(\n  /** Element you want to ignore */\n  ignoredElementsQuerySelector: string,\n  /** Main app element (if you want for the page to be loaded before triggering the command) */\n  appContentQuerySelector: string = 'body'\n) {\n  Cypress.Commands.overwrite('compareSnapshot', (originalFn, ...args) =\u003e {\n    return (\n      cy\n        // wait for content to be ready\n        .get(appContentQuerySelector)\n        // hide ignored elements\n        .then(($app) =\u003e {\n          return new Cypress.Promise((resolve, reject) =\u003e {\n            setTimeout(() =\u003e {\n              $app.find(ignoredElementsQuerySelector).css('visibility', 'hidden')\n              resolve()\n              // add a very small delay to wait for the elements to be there, but you should\n              // make sure your test already handles this\n            }, 300)\n          })\n        })\n        .then(() =\u003e {\n          return originalFn(...args)\n        })\n    )\n  })\n}\n```\n\nYou may then use this function like:\n\n```js\nconst { addCompareSnapshotCommand } = require('cypress-visual-regression/dist/command')\nconst beforeCompareSnapshots = require('./commands/beforeCompareSnapshots')\naddCompareSnapshotCommand({\n  errorThreshold: 0.1\n})\n// add a before hook to compareSnapshot (this must be called AFTER compareSnapshotCommand() so the command can be overriden)\nbeforeCompareSnapshots(\".chromatic-ignore,[data-chromatic='ignore']\", '._app-content')\n```\n\nIn this example, we ignore the elements that are also ignored by 3rd party tool Chromatic.\n\n## Debug\n\nset process env `visual_regression_log` to `debug` to enable logging:\n\n```bash\nvisual_regression_log=debug cypress open --e2e -b chrome -C cypress.base.config.ts\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-visual-regression%2Fcypress-visual-regression","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcypress-visual-regression%2Fcypress-visual-regression","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcypress-visual-regression%2Fcypress-visual-regression/lists"}