Migrate from v1 to v2

In a mission to provide a robust and easy-to-use visual regression tool for front-end development, Cypress Image Diff version 2 introduces Cypress Image Diff HTML Report as a separate npm package with extensive features and provides a new compareSnapshot arguments type.

New HTML Report

We've separated out the core plugin and the HTML report (under the name of Cypress Image Diff HTML Report) with the aim of providing a beautiful interactive HTML report with a JSON file with all the details about your test suites, together with extensive features:

• Update baseline screenshots

• Toggle between different screenshot inspector modes: carousel, slider, and mirror

• Select your preferred colour scheme

Although Cypress Image Diff HTML Report is a standalone npm package, the integration with the core Cypress Image Diff is seamless, and they are expected to work together out of the box without any further configuration.

Note: The old report still continues to function in Cypress Image Diff version 2, but it is planned to be deprecated once the Cypress Image Diff HTML Report reaches its stable state.

---

New compareSnapshot arguments type

• compareSnapshot now could accept new arguments: cypressScreenshotOptions and exactName

• New global config option: CYPRESS_SCREENSHOT_OPTIONS

// cypress-image-diff v1.32.0 and older
cy.compareSnapshot('header')
cy.compareSnapshot('header', 0.2)
cy.compareSnapshot('header', 0.2, { limit: 6, delay: 1000 })

// cypress-image-diff v2.0.0 and newer
cy.compareSnapshot('header')
cy.compareSnapshot({
  name: 'header',
  testThreshold: 0.2
})
cy.compareSnapshot({
  name: 'header',
  testThreshold: 0.2,
  recurseOptions: { limit: 6, delay: 1000 }
})
cy.compareSnapshot({
  name: 'header',
  testThreshold: 0.2,
  recurseOptions: { limit: 6, delay: 1000 },
  // new custom cypress screenshot options
  cypressScreenshotOptions: {
    clip: { x: 0, y: 0, width: 100, height: 100 }
  }
  // new exactName option
  exactName: true
})

---

Rename import path

🚫 import getCompareSnapshotsPlugin from 'cypress-image-diff-js/dist/plugin';
✅ import getCompareSnapshotsPlugin from 'cypress-image-diff-js/plugin';

🚫 import compareSnapshotCommand from 'cypress-image-diff-js/dist/command';
✅ import compareSnapshotCommand from 'cypress-image-diff-js/command';

---

Rename default screenshots and report folder

🚫 cypress-visual-screenshots
✅ cypress-image-diff-screenshots

🚫 cypress-visual-report
✅ cypress-image-diff-html-report

---

New config options

• make screenshots and report folder configurable

// cypress-image-diff.config.js
const config = {
  REPORT_DIR: 'html-report',
  SCREENSHOTS_DIR: 'visual-screenshots'
};

module.exports = config;

Note: REPORT_DIR and SCREENSHOTS_DIR only work for Cypress Image Diff Html Report, and this is intentional. Please consider using Cypress Image Diff Html Report for better support.

---