Releases: FRSOURCE/cypress-plugin-visual-regression-diff
Release list
@frsource/cypress-plugin-visual-regression-diff: v4.1.1
@frsource/cypress-plugin-visual-regression-diff: v4.1.0
@frsource/cypress-plugin-visual-regression-diff: v4.0.2
4.0.2 (2026-06-28)
Bug Fixes
@frsource/cypress-plugin-visual-regression-diff: v4.0.1
@frsource/cypress-plugin-visual-regression-diff: v4.0.0
4.0.0 (2026-06-26)
⚠ BREAKING CHANGES
- Cypress minimum version raised to 13
- Node.js minimum version raised to 14
- Attempt separator changed: space → underscore (resolves #196)
The number appended to snapshot filenames on retried attempts is now separated by an underscore instead of a space.
| Before | After |
|---|---|
test name #0.png |
test name_#0.png |
Migration: regenerate your baseline snapshots, or batch-rename existing files:
# Example rename (macOS/Linux)
find . -name "* #*.png" | while read f; do
mv "$f" "${f/ #/_#}"
doneimagesDir option removed
The imagesDir option was deprecated in v3 and has been fully removed. Use imagesPath instead.
- pluginVisualRegressionImagesDir: 'cypress/__image_snapshots__'
+ pluginVisualRegressionImagesPath: 'cypress/__image_snapshots__'For migration, look to the end of release note.
Features
A new value for the existing updateImages option. When set, baselines are only overwritten when the diff exceeds the configured threshold — unchanged screenshots are left as-is. This is particularly useful for CI jobs that capture screenshots on a reference platform: images that haven't changed are skipped, speeding up the run.
cy.matchImage({ updateImages: 'failures-only' });
// or as a global default in cypress.config.js:
pluginVisualRegressionUpdateImages: 'failures-only'A new cypressPluginVisualRegressionDiff:processImgPath Cypress task is called after every screenshot, giving you full control over where the file ends up. By default it is a no-op, but you can override it in setupNodeEvents to integrate with reporters such as cypress-mochawesome-reporter:
// cypress.config.js
on('task', {
'cypressPluginVisualRegressionDiff:processImgPath'({ imgPath }) {
// return a modified path, or return imgPath unchanged
return imgPath;
},
});Bug Fixes
- "Update screenshot" button now respects
matchAgainstPath(resolves #259, #282) - Auto-cleanup no longer deletes snapshots from the other testing type (fixes #178)
Dependency Upgrades
| Dependency | Old | New | Notes |
|---|---|---|---|
| Cypress (peer) | ≥ 10 | ≥ 13 | |
| sharp | 0.32.x | 0.33.5 | Resolves CVE-2023-4863 (libwebp vulnerability) |
| Node.js (engine) | ≥ 12 | ≥ 14 | Aligned with Cypress 13 |
| Vitest | 1.x | 2.x | Internal — does not affect plugin consumers |
- deps: update all non-major dependency bump (#260) (da9f52c)
- deps: update all non-major dependency bump (#268) (4bc8247)
- deps: update all non-major dependency bump (#274) (3ff8d88)
- deps: update all non-major dependency bump (#283) (a2d7379)
- deps: update all non-major dependency bump (#285) (aea122c)
- deps: update all non-major dependency bump (#297) (6ac55f0)
- deps: update all non-major dependency bump (#298) (2181dcf)
- deps: update all non-major dependency bump (#312) (e265d7b)
- deps: update dependency @frsource/base64 to v1.0.26 (#288) (36aafcd)
Documentation
New FAQ entries have been added covering:
- Screenshot size differences between
cypress runandcypress open(#294) — useforceDeviceScaleFactor: trueto normalise the device pixel ratio. - Composing with other plugins that also register
setupNodeEvents(#302) — usecypress-on-fixto avoid handlers overwriting each other. - Integrating diff images with mochawesome (#106) — use the new
processImgPathhook to point the reporter at the correct path. - Answers to several long-standing community discussions: #96, #189, #214, #226, #309.