{"id":13711801,"url":"https://github.com/jaredpalmer/cypress-image-snapshot","last_synced_at":"2025-05-16T10:06:27.599Z","repository":{"id":38303773,"uuid":"138782426","full_name":"jaredpalmer/cypress-image-snapshot","owner":"jaredpalmer","description":"Catch visual regressions in Cypress","archived":false,"fork":false,"pushed_at":"2024-04-10T19:04:58.000Z","size":1954,"stargazers_count":893,"open_issues_count":124,"forks_count":156,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-14T17:08:21.534Z","etag":null,"topics":["cypress","cypress-plugin","image-diff","image-diffs","jest-image-snapshot","visual-regression","visual-regression-testing","visual-regression-tests"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/jaredpalmer.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":["jaredpalmer"]}},"created_at":"2018-06-26T19:15:47.000Z","updated_at":"2025-05-04T12:22:07.000Z","dependencies_parsed_at":"2024-05-13T00:47:15.088Z","dependency_job_id":null,"html_url":"https://github.com/jaredpalmer/cypress-image-snapshot","commit_stats":{"total_commits":125,"total_committers":14,"mean_commits":8.928571428571429,"dds":0.344,"last_synced_commit":"0510252bc5f192c410bcca45b511f07737bce4a2"},"previous_names":["palmerhq/cypress-image-snapshot"],"tags_count":35,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpalmer%2Fcypress-image-snapshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpalmer%2Fcypress-image-snapshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpalmer%2Fcypress-image-snapshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaredpalmer%2Fcypress-image-snapshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaredpalmer","download_url":"https://codeload.github.com/jaredpalmer/cypress-image-snapshot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254509475,"owners_count":22082891,"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","image-diffs","jest-image-snapshot","visual-regression","visual-regression-testing","visual-regression-tests"],"created_at":"2024-08-02T23:01:11.766Z","updated_at":"2025-05-16T10:06:27.571Z","avatar_url":"https://github.com/jaredpalmer.png","language":"JavaScript","funding_links":["https://github.com/sponsors/jaredpalmer"],"categories":["Uncategorized","JavaScript"],"sub_categories":["Uncategorized"],"readme":"# Cypress Image Snapshot\n\n\nCypress Image Snapshot binds [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot)'s image diffing logic to [Cypress.io](https://cypress.io) commands. **The goal is to catch visual regressions during integration tests.**\n\n[![Discord](https://img.shields.io/discord/769256827007139912?label=%F0%9F%92%AC%20%20join%20us%20on%20discord\u0026style=plastic)](https://discord.com/invite/RevdZTYMzr)\n\n\u003cdetails\u003e\n\u003csummary\u003eSee it in action!\u003c/summary\u003e\n\n### Cypress GUI\n\nWhen using `cypress open`, errors are displayed in the GUI.\n\n\u003cimg width=\"500px\" src=\"https://user-images.githubusercontent.com/4060187/41942389-5a6705ae-796d-11e8-8003-fadbf7ccf43d.gif\" alt=\"Cypress Image Snapshot in action\"/\u003e\n\n### Composite Image Diff\n\nWhen an image diff fails, a composite image is constructed.\n\n\u003cimg width=\"500px\" src=\"https://user-images.githubusercontent.com/4060187/41942163-72c8c20a-796c-11e8-9149-c295341864d3.png\" alt=\"Cypress Image Snapshot diff\"/\u003e\n\n### Test Reporter\n\nWhen using `cypress run` and `--reporter cypress-image-snapshot/reporter`, diffs are output to your terminal.\n\n\u003cimg width=\"500px\" src=\"https://user-images.githubusercontent.com/1153686/48518011-303d4580-e836-11e8-83ed-776acae78f9f.png\" alt=\"Cypress Image Snapshot reporter\"/\u003e\n\n\u003c/details\u003e\n\n## Installation\n\nInstall from npm\n\n```bash\nnpm install --save-dev cypress-image-snapshot\n```\n\nthen add the following in your project's `\u003crootDir\u003e/cypress/plugins/index.js`:\n\n```js\nconst {\n  addMatchImageSnapshotPlugin,\n} = require('cypress-image-snapshot/plugin');\n\nmodule.exports = (on, config) =\u003e {\n  addMatchImageSnapshotPlugin(on, config);\n};\n```\n\nand in `\u003crootDir\u003e/cypress/support/commands.js` add:\n\n```js\nimport { addMatchImageSnapshotCommand } from 'cypress-image-snapshot/command';\n\naddMatchImageSnapshotCommand();\n```\n\n## Syntax\n\n```js\n// addMatchImageSnapshotPlugin\naddMatchImageSnapshotPlugin(on, config);\n\n// addMatchImageSnapshotCommand\naddMatchImageSnapshotCommand();\naddMatchImageSnapshotCommand(commandName);\naddMatchImageSnapshotCommand(options);\naddMatchImageSnapshotCommand(commandName, options);\n\n// matchImageSnapshot\n.matchImageSnapshot();\n.matchImageSnapshot(name);\n.matchImageSnapshot(options);\n.matchImageSnapshot(name, options);\n\n// ---or---\n\ncy.matchImageSnapshot();\ncy.matchImageSnapshot(name);\ncy.matchImageSnapshot(options);\ncy.matchImageSnapshot(name, options);\n```\n\n## Usage\n\n### In your tests\n\n```js\ndescribe('Login', () =\u003e {\n  it('should be publicly accessible', () =\u003e {\n    cy.visit('/login');\n\n    // snapshot name will be the test title\n    cy.matchImageSnapshot();\n\n    // snapshot name will be the name passed in\n    cy.matchImageSnapshot('login');\n\n    // options object passed in\n    cy.matchImageSnapshot(options);\n\n    // match element snapshot\n    cy.get('#login').matchImageSnapshot();\n  });\n});\n```\n\n### Updating snapshots\n\nRun Cypress with `--env updateSnapshots=true` in order to update the base image files for all of your tests.\n\n### Preventing failures\n\nRun Cypress with `--env failOnSnapshotDiff=false` in order to prevent test failures when an image diff does not pass.\n\n### Reporter\n\nRun Cypress with `--reporter cypress-image-snapshot/reporter` in order to report snapshot diffs in your test results. This can be helpful to use with `--env failOnSnapshotDiff=false` in order to quickly view all failing snapshots and their diffs.\n\nIf you using [iTerm2](https://www.iterm2.com/version3.html), the reporter will output any image diffs right in your terminal 😎.\n\n#### Multiple reporters\n\nSimilar use case to: https://github.com/cypress-io/cypress-example-docker-circle#spec--xml-reports\n\nIf you want to report snapshot diffs as well as generate XML junit reports, you can use [mocha-multi-reporters](https://github.com/stanleyhlng/mocha-multi-reporters).\n\n```\nnpm install --save-dev mocha mocha-multi-reporters mocha-junit-reporter\n```\n\nYou'll then want to set up a `cypress-reporters.json` which may look a little like this:\n\n```json\n{\n  \"reporterEnabled\": \"spec, mocha-junit-reporter, cypress-image-snapshot/reporter\",\n  \"mochaJunitReporterReporterOptions\": {\n    \"mochaFile\": \"cypress/results/results-[hash].xml\"\n  }\n}\n```\n\nwhere `reporterEnabled` is a comma-separated list of reporters.\n\nYou can then run cypress like this:\n\n`cypress run --reporter mocha-multi-reporters --reporter-options configFile=cypress-reporters.json`\n\nor add the following to your `cypress.json`\n\n```\n{\n  ..., //other options\n  \"reporter\": \"mocha-multi-reporters\",\n  \"reporterOptions\": {\n    \"configFile\": \"cypress-reporters.json\"\n  }\n}\n```\n\n## Options\n\n- `customSnapshotsDir` : Path to the directory that snapshot images will be written to, defaults to `\u003crootDir\u003e/cypress/snapshots`.\n- `customDiffDir`: Path to the directory that diff images will be written to, defaults to a sibling `__diff_output__` directory alongside each snapshot.\n\nAdditionally, any options for [`cy.screenshot()`](https://docs.cypress.io/api/commands/screenshot.html#Arguments) and [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot#optional-configuration) can be passed in the `options` argument to `addMatchImageSnapshotCommand` and `cy.matchImageSnapshot()`. The local options in `cy.matchImageSnapshot()` will overwrite the default options set in `addMatchImageSnapshot`.\n\nFor example, the default options we use in `\u003crootDir\u003e/cypress/support/commands.js` are:\n\n```js\naddMatchImageSnapshotCommand({\n  failureThreshold: 0.03, // threshold for entire image\n  failureThresholdType: 'percent', // percent of image or number of pixels\n  customDiffConfig: { threshold: 0.1 }, // threshold for each pixel\n  capture: 'viewport', // capture viewport in screenshot\n});\n```\n\n## How it works\n\nWe really enjoy the diffing workflow of jest-image-snapshot and wanted to have a similar workflow when using Cypress. Because of this, under the hood we use some of jest-image-snapshot's internals and simply bind them to Cypress's commands and plugins APIs.\n\nThe workflow of `cy.matchImageSnapshot()` when running Cypress is:\n\n1.  Take a screenshot with `cy.screenshot()` named according to the current test.\n2.  Check if a saved snapshot exists in `\u003crootDir\u003e/cypress/snapshots` and if so diff against that snapshot.\n3.  If there is a resulting diff, save it to `\u003crootDir\u003e/cypress/snapshots/__diff_output__`.\n\n## Cypress Version Requirements\n\nCypress's screenshot functionality has changed significantly across `3.x.x` versions. In order to avoid buggy behavior, please use the following version ranges:\n\n- `cypress-image-snapshot@\u003e=1.0.0 \u003c2.0.0` for `cypress@\u003e=3.0.0 \u003c3.0.2`\n- `cypress-image-snapshot@\u003e2.0.0` for `cypress@\u003e3.0.2`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredpalmer%2Fcypress-image-snapshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaredpalmer%2Fcypress-image-snapshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaredpalmer%2Fcypress-image-snapshot/lists"}