{"id":16346843,"url":"https://github.com/simonsmith/cypress-image-snapshot","last_synced_at":"2025-04-06T06:11:02.540Z","repository":{"id":166734346,"uuid":"628069295","full_name":"simonsmith/cypress-image-snapshot","owner":"simonsmith","description":"Catch visual regressions in Cypress with jest-image-snapshot","archived":false,"fork":false,"pushed_at":"2024-09-16T21:08:59.000Z","size":1580,"stargazers_count":64,"open_issues_count":7,"forks_count":15,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-18T08:40:28.851Z","etag":null,"topics":["cypress","integration-testing","visual-regression"],"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/simonsmith.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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}},"created_at":"2023-04-14T20:56:10.000Z","updated_at":"2024-09-16T21:09:03.000Z","dependencies_parsed_at":"2023-12-29T13:24:56.097Z","dependency_job_id":"3b98c01c-20dd-40e8-9e4f-7c95e4f18437","html_url":"https://github.com/simonsmith/cypress-image-snapshot","commit_stats":{"total_commits":146,"total_committers":18,"mean_commits":8.11111111111111,"dds":0.4383561643835616,"last_synced_commit":"e98fdc0030645e209ddce54fda729412e66b14bb"},"previous_names":["simonsmith/cypress-image-snapshot"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fcypress-image-snapshot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fcypress-image-snapshot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fcypress-image-snapshot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonsmith%2Fcypress-image-snapshot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonsmith","download_url":"https://codeload.github.com/simonsmith/cypress-image-snapshot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247441053,"owners_count":20939239,"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","integration-testing","visual-regression"],"created_at":"2024-10-11T00:37:55.697Z","updated_at":"2025-04-06T06:11:02.500Z","avatar_url":"https://github.com/simonsmith.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cypress Image Snapshot\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.\n\n[![build-and-test](https://github.com/simonsmith/cypress-image-snapshot2/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/simonsmith/cypress-image-snapshot2/actions/workflows/build-and-test.yml)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Installation](#installation)\n  - [TypeScript](#typescript)\n- [Usage](#usage)\n  - [In your tests](#in-your-tests)\n  - [Options](#options)\n    - [Snapshot paths](#snapshot-paths)\n  - [Updating snapshots](#updating-snapshots)\n  - [Preventing failures](#preventing-failures)\n  - [Requiring snapshots to be present](#requiring-snapshots-to-be-present)\n- [How it works](#how-it-works)\n- [Requirements](#requirements)\n- [Contributing](#contributing)\n  - [Setup](#setup)\n  - [Working on the plugin](#working-on-the-plugin)\n    - [open](#open)\n    - [run](#run)\n      - [Note on environment variables](#note-on-environment-variables)\n- [Forked from `jaredpalmer/cypress-image-snapshot`](#forked-from-jaredpalmercypress-image-snapshot)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\nInstall with your chosen package manager\n\n```bash\n# yarn\nyarn add --dev @simonsmith/cypress-image-snapshot\n\n# npm\nnpm install --save-dev @simonsmith/cypress-image-snapshot\n```\n\nNext, import the plugin function and add it to the [`setupNodeEvents` function](https://docs.cypress.io/guides/references/configuration#setupNodeEvents):\n\n```ts\n// cypress.config.ts\n\nimport {defineConfig} from 'cypress'\nimport {addMatchImageSnapshotPlugin} from '@simonsmith/cypress-image-snapshot/plugin'\n\nexport default defineConfig({\n  e2e: {\n    setupNodeEvents(on) {\n      addMatchImageSnapshotPlugin(on)\n    },\n  },\n})\n```\n\nAdd the command to your relevant [support file](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Support-file):\n\n```ts\n// cypress/support/e2e.ts\n\nimport {addMatchImageSnapshotCommand} from '@simonsmith/cypress-image-snapshot/command'\n\naddMatchImageSnapshotCommand()\n\n// can also add any default options to be used\n// by all instances of `matchImageSnapshot`\naddMatchImageSnapshotCommand({\n  failureThreshold: 0.2,\n})\n```\n\n### TypeScript\n\nTypeScript is supported so any reference to `@types/cypress-image-snapshot` can be removed from your project\n\nEnsure that the types are included in your `tsconfig.json`\n\n```\n{\n  \"compilerOptions\": {\n    // ...\n  },\n  \"types\": [\"@simonsmith/cypress-image-snapshot/types\"]\n}\n```\n\n## Usage\n\n### In your tests\n\n```ts\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    // snapshot will be created inside `some/dir`\n    cy.matchImageSnapshot('some/dir/image')\n\n    // options object passed in\n    cy.matchImageSnapshot({\n      failureThreshold: 0.4\n      blur: 10\n    });\n\n    // match element snapshot\n    cy.get('#login').matchImageSnapshot();\n  });\n});\n```\n\n### Options\n\nThe options object combines jest-image-snapshot and Cypress screenshot configuration.\n\n- [jest-image-snapshot](https://github.com/americanexpress/jest-image-snapshot#%EF%B8%8F-api)\n- [Cypress screenshot](https://docs.cypress.io/api/commands/screenshot#Arguments)\n\n```ts\ncy.matchImageSnapshot({\n  // options for jest-image-snapshot\n  failureThreshold: 0.2,\n  comparisonMethod: 'ssim',\n\n  // options for Cypress.screenshot()\n  capture: 'viewport',\n  blackout: ['.some-element'],\n})\n```\n\nIt is also possible to configure the extensions given to snap and diff files\ngenerated by the plugin. The default options are:\n\n```ts\n{\n  snapFilenameExtension: '.snap',\n  diffFilenameExtension: '.diff',\n}\n```\n\n```ts\n// will create a snap called `some-name.custom-snap-name.png`\ncy.matchImageSnapshot('some-name', {\n  snapFilenameExtension: '.custom-snap-name',\n})\n\n// will create a snap called `some-name.png`\ncy.matchImageSnapshot('some-name', {\n  snapFilenameExtension: '',\n})\n\n// will create a diff called `some-name.wrong.png` when a test fails\ncy.matchImageSnapshot('some-name', {\n  diffFilenameExtension: '.wrong',\n})\n```\n\n#### Snapshot paths\n\nAs of Cypress 10.0.0 a change was made to remove common ancestor paths of\ngenerated screenshots. This means that it is difficult to mimic the folder\nstructure found in the `cypress/e2e/` directory when creating the `snapshots`\ndirectory.\n\nTo workaround this, cypress-image-snapshot makes use of a `e2eSpecDir`\noption. Here's an example:\n\n```ts\naddMatchImageSnapshotCommand({\n  e2eSpecDir: 'cypress/e2e/', // the default value\n})\n```\n\nExample output in a project:\n\n```\ncypress\n├── e2e\n│  ├── matchImageSnapshot.cy.ts\n│  ├── nested\n│  │  └── test\n│  └── someOtherTest.cy.ts\n├── snapshots\n│  ├── matchImageSnapshot.cy.ts\n│  │  ├── matches with just options.snap.png\n│  │  ├── name and options.snap.png\n│  │  ├── no arguments.snap.png\n│  │  └── with custom name.snap.png\n│  ├── nested\n│  │  └── test\n│  └── someOtherTest.cy.ts\n│     └── some other test taking a snapshot.snap.png\n```\n\nWithout the `e2eSpecDir` option the `cypress/e2e/` directories would be\nrepeated inside the `snapshots` directory. Set this option to whatever\ndirectory structure is inside the `specPattern` [configuration value](https://docs.cypress.io/guides/references/configuration#e2e).\n\nSee more:\n\n- https://github.com/cypress-io/cypress/issues/22159\n- https://github.com/cypress-io/cypress/issues/24052\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\nBy default tests will fail when a snapshot fails to match. Run Cypress with\n`--env failOnSnapshotDiff=false` in order to prevent test failures when an image\ndiff does not pass.\n\n### Requiring snapshots to be present\n\nRun Cypress with `--env requireSnapshots=true` in order to fail if snapshots are missing. This is useful in continuous integration where snapshots should be present in advance.\n\n## How it works\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## Requirements\n\nTested on Cypress 10.x, 11.x and 12.x\n\nCypress must be installed as a peer dependency\n\n## Contributing\n\n### Setup\n\n- Clone the repository and install the yarn dependencies with `yarn install`\n- Ensure that Docker is setup. This is necessary for generating/updating snapshots\n- Using [Volta](https://volta.sh/) is recommended for managing Node and Yarn versions. These are\n  automatically picked up from the `package.json`\n- Commits should be based on [conventional-changelog](https://github.com/pvdlg/conventional-changelog-metahub#commit-types)\n\n### Working on the plugin\n\nTo make it easier to test whilst developing there are a few simple\nCypress tests that validate the plugin. There are two ways to run these tests:\n\n#### open\n\n`yarn test:open`\n\nIn open mode the tests run in Electron and ignore any snapshot failures. This is\ndue to the rendering differences on developer machines vs CI. Here there is also\nverbose output sent to the test runner console to aid debugging.\n\n**Note** here that the yarn script above will re-build the plugin each time. This is\nnecessary because the tests are run against the output in the `dist` directory\nto ensure parity between the built package on NPM.\n\nEnsure that the command is run each time changes need to be tested in Cypress\n\n#### run\n\n- `yarn docker:build`\n- `yarn docker:run`\n\nThe commands here ensure that the tests are run inside a Docker container that\nmatches the CI machine. This allows images to be generated and matched correctly\nwhen running the tests in Github Actions.\n\n##### Note on environment variables\n\nIt is necessary to have two environment variables defined by default before\nrunning the tests in Docker:\n\n- `CYPRESS_updateSnapshots=false`\n- `CYPRESS_debugSnapshots=false`\n\nIt's recommended that these are loaded into the shell with something like [direnv](https://direnv.net/)\n\nThen they can be overridden as needed:\n\n```\nCYPRESS_updateSnapshots=true yarn docker:run\n```\n\n## Forked from `jaredpalmer/cypress-image-snapshot`\n\nThis is a rewrite of the original plugin as active development has ceased. Full credit goes to [Jared Palmer](https://github.com/jaredpalmer).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonsmith%2Fcypress-image-snapshot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonsmith%2Fcypress-image-snapshot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonsmith%2Fcypress-image-snapshot/lists"}