Utility to take screenshots during a cypress test and match them against previous runs

Downloads in past


1.1.06 years ago6 years agoMinified + gzip package size for cypress-match-screenshot in KB


npm version
Utility to take screenshots during a cypress test and match them against previous runs.


Cypress is actively working on a feature like this, see With that in mind this package should only be seen as temporary solution until Cypress publishes their official solution … but if you're like me and want to do some screenshot matching rather sooner than later, feel free to give it a shot 😄


yarn add cypress-match-screenshot --dev

Then register the custom command in your cypress/support/commands.js file:
import { register } from 'cypress-match-screenshot';

That's it, now you can use the feature like this:
describe('Example', function () {
  it('Should match screenshot', function () {
    cy.matchScreenshot('Google Screenshot');

On the first run the assertion will always pass and the tool will just store the screenshot. On subsequent runs it will take a screenshot and compare it to the previous one. Only if the difference is below the threshold the assertion will pass and the old screenshot will be replaced by the new one.
You can find all diffs as images in cypress/screenshots/diff to see what excactly changed 😊


NOTE: I haven't played around with screenshot matching in CI, so treat everything in here careful and please feel free to add / edit anything if you find missing or wrong information 😊

Keep screenshots around to be matched
By default Cypress deletes all the screenshots before running tests in CI mode. To disable that (to keep the screenshots around so they can be matched in subsequent runs) just add the following to your cypress.json config:
  "trashAssetsBeforeHeadlessRuns": false



name (optional)
You can optionally define the name you want the functionality to be registered on. By default its matchScreenshot.
import { register } from 'cypress-match-screenshot'

// then in the test

Match screenshot method

cy.matchScreenshot(name, {

If you have multiple screenshots within the same test case, you need to give them unique names so that the matcher can identify which image it should match to. It also makes it easier for you to find the image in the screenshots folder.
The general rule for screenshot naming is: [Test Suit Name] -- [Test Name] -- [Screenshot Name].png
threshold: Threshold for the screenshot matching, default: 0.005 thresholdType: unit for the threshold,pixel or percent, default: percent

Update screenshots

If you want to update the base screenshots with the new generated set, put the updateScreenshots parameter to your Cypress config. This will allow your tests to pass and the base screenshots being replaced by the new ones.