cypress-snapshot-reporter

Cypress plugin for full-page visual snapshot testing with pixel-level diffs, composite diff images, optional OCR, and Excel reports.

• Node.js >= 16 | Cypress >= 13
• Peer: cypress-mochawesome-reporter@^3

Installation

npm install --save-dev cypress-snapshot-reporter cypress-mochawesome-reporter@^3

Quick Start

1. Configure Plugin

In cypress.config.js:

const { defineConfig } = require("cypress");
const { setupSnapshots } = require("cypress-snapshot-reporter/plugin");

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      setupSnapshots(on, config);
      return config;
    },
  },
});

2. Import Commands

In cypress/support/e2e.js:

import "cypress-mochawesome-reporter/register";
import "cypress-snapshot-reporter/commands";

3. Use in Tests

cy.visit("/dashboard");
cy.matchSnapshot("Dashboard/2025-05-22");

On first run, baseline is created automatically. Subsequent runs compare against baseline and report diffs.

setupSnapshots(on, config, options)

| Option | Default | Description | |--------|---------|-------------| | baselineDir | cypress/snapshots/baseline | Baseline PNG root | | actualDir | cypress/snapshots/actual | Current run screenshots | | diffDir | cypress/snapshots/diff | Composite diff images | | excelFile | cypress/snapshots/reports/diff-report.xlsx | OCR report workbook | | browserWidth | 6400 | Electron window width | | browserHeight | 4400 | Electron window height | | flatScreenshots | true | Flat folder structure (no spec-prefixed paths) |

cy.matchSnapshot(name, options)

cy.matchSnapshot("Reports/Section/Name", {
  threshold: 0.1,        // Color diff sensitivity (0-1)
  failOnDiff: false,     // Fail test on visual diff
  runOcr: true,          // Extract text from changed regions
});

Snapshot names support / at any depth:

• "Dashboard" → cypress/snapshots/baseline/Dashboard.png
• "Reports/2025/Q1" → cypress/snapshots/baseline/Reports/2025/Q1.png

Features

Flat Screenshot Structure

When flatScreenshots: true (default), the plugin manages folder structure automatically—no Cypress spec-prefixed folders. You control the hierarchy via snapshot names.

Composite Diffs

On visual diff:

[ baseline ] | [ diff (red highlights) ] | [ actual ]

OCR on Changes

Automatically extracts text from changed regions and appends to Excel report (when runOcr: true).

Severity Levels

Based on % of pixels that differ:

| Level | % Changed | |-------|-----------| | Critical | > 2.0% | | High | > 0.5% | | Medium | > 0.05% | | Low | > 0% |

Update Baseline

cy.task("updateBaseline", { name: "Dashboard" });

Folder Structure

cypress/snapshots/
├── baseline/          # Reference images
│   └── Reports/
│       └── Dashboard.png
├── actual/            # Current run images
│   └── Reports/
│       └── Dashboard.png
├── diff/              # Composite diffs (on mismatch)
│   └── Reports/
│       └── Dashboard.png
└── reports/
    └── diff-report.xlsx

Examples

Basic Snapshot

describe("Financial Reports", () => {
  it("displays dashboard correctly", () => {
    cy.visit("/dashboard");
    cy.matchSnapshot("Reports/Dashboard_2025-05-22");
  });
});

With Fail on Diff

cy.matchSnapshot("Critical/Report", { failOnDiff: true });

With Custom Sensitivity

cy.matchSnapshot("Tolerance/Test", { threshold: 0.05 });

Tips

• Nested names: Use forward slashes for organization (Reports/Q1/Dashboard)
• First run: Creates baseline automatically
• Update: Run test again after intentional UI changes to update baseline
• OCR: Requires Tesseract data (bundled; offline mode)

License

MIT