chore: merge branch 'main' into feat/deferred-failures-and-batch-review-ui

# Conflicts:
#	packages/cypress-plugin-visual-regression-diff/src/commands.ts

Author: FRSgit

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  "packages/cypress-plugin-visual-regression-diff": "4.0.2"
+  "packages/cypress-plugin-visual-regression-diff": "4.1.0"
 }

examples/next/package.json

@@ -4,7 +4,7 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "cypress": "cypress open --env \"pluginVisualRegressionUpdateImages=true,pluginVisualRegressionImagesPath={spec_path}/__image_snapshots_local__\"",
+    "cypress": "cypress open --env \"pluginVisualRegressionImagesPath={spec_path}/__image_snapshots_local__\"",
     "cypress:ci": "cypress run --env \"pluginVisualRegressionUpdateImages=true\"",
     "test:e2e": "start-server-and-test dev http://localhost:3000 \"pnpm cypress --e2e\"",
     "test:e2e:ci": "start-server-and-test dev http://localhost:3000 \"pnpm cypress:ci --e2e\"",

package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "build": "pnpm -r build",
     "lint": "eslint '**/*.ts' --ignore-pattern '**/*.d.ts'",
-    "lint:fix": "pnpm lint --fix",
+    "fix": "pnpm lint --fix",
     "lint:ci": "pnpm lint --max-warnings 0",
     "format": "pnpm -r format",
     "format:ci": "pnpm -r format:ci",

packages/cypress-plugin-visual-regression-diff/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [4.1.0](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/compare/@frsource/cypress-plugin-visual-regression-diff-v4.0.2...@frsource/cypress-plugin-visual-regression-diff-v4.1.0) (2026-07-02)
+
+
+### Features
+
+* migrate plugin options from Cypress.env() to Cypress.expose() in preparation for Cypress 16 ([#376](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/issues/376)) ([2b71557](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/commit/2b7155700bcddbbef92c5c42d0e5fe05beb3fa00)), closes [#375](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/issues/375). For migration guide, go to this link: https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/blob/main/packages/cypress-plugin-visual-regression-diff/MIGRATION.md#40x---41x
+
 ## [4.0.2](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/compare/@frsource/cypress-plugin-visual-regression-diff-v4.0.1...@frsource/cypress-plugin-visual-regression-diff-v4.0.2) (2026-06-28)
 
 

packages/cypress-plugin-visual-regression-diff/MIGRATION.md

@@ -0,0 +1,98 @@
+# Migration Guide
+
+## 4.0.x -> 4.1.x
+
+### Migrating to Cypress 16 (`Cypress.expose` API)
+
+Cypress 16 removes `Cypress.env()` in favor of the new `Cypress.expose()` API (introduced in Cypress 15.10.0).
+This plugin supports both APIs automatically based on the detected Cypress version:
+
+- **Cypress ≥ 15.10** – reads plugin options via `Cypress.expose()` / `config.expose`
+- **Cypress < 15.10** – reads plugin options via `Cypress.env()` / `config.env` (legacy)
+
+No code change is required inside your tests. You only need to update **how you supply plugin options**.
+
+### What changed
+
+| Location            | Before (all Cypress versions) | After (Cypress ≥ 15.10)                     |
+| ------------------- | ----------------------------- | ------------------------------------------- |
+| CLI flag            | `--env "key=value"`           | `--expose "key=value"`                      |
+| `cypress.config.ts` | `env: { key: value }`         | `expose: { key: value }`                    |
+| `cypress.env.json`  | `{ "key": "value" }`          | use `expose` in `cypress.config.ts` instead |
+
+### Plugin option names
+
+All option names stay the same — they are prefixed with `pluginVisualRegression`:
+
+| Option                   | Config key                                     |
+| ------------------------ | ---------------------------------------------- |
+| `updateImages`           | `pluginVisualRegressionUpdateImages`           |
+| `cleanupUnusedImages`    | `pluginVisualRegressionCleanupUnusedImages`    |
+| `diffConfig`             | `pluginVisualRegressionDiffConfig`             |
+| `forceDeviceScaleFactor` | `pluginVisualRegressionForceDeviceScaleFactor` |
+| `maxDiffThreshold`       | `pluginVisualRegressionMaxDiffThreshold`       |
+
+### CLI
+
+```bash
+# Before (deprecated in 15.10, removed in 16)
+npx cypress run --env "pluginVisualRegressionUpdateImages=true"
+
+# After (Cypress ≥ 15.10)
+npx cypress run --expose "pluginVisualRegressionUpdateImages=true"
+```
+
+### cypress.config.ts
+
+```ts
+// Before
+export default defineConfig({
+  env: {
+    pluginVisualRegressionUpdateImages: true,
+    pluginVisualRegressionDiffConfig: { threshold: 0.01 },
+  },
+});
+
+// After (Cypress ≥ 15.10)
+export default defineConfig({
+  expose: {
+    pluginVisualRegressionUpdateImages: true,
+    pluginVisualRegressionDiffConfig: { threshold: 0.01 },
+  },
+});
+```
+
+### cypress.env.json
+
+`cypress.env.json` only works with `Cypress.env()` and is not supported by the `expose` API.
+Migrate any plugin options from `cypress.env.json` into the `expose` block of `cypress.config.ts`.
+
+```jsonc
+// cypress.env.json — REMOVE these plugin keys:
+{
+  // "pluginVisualRegressionUpdateImages": true,  ← move to cypress.config.ts expose block
+}
+```
+
+### Supporting both Cypress 15.x and 16.x simultaneously
+
+If you need your config to work on both Cypress 15.9 and below **and** 15.10+, you can supply the
+option in both places — the plugin will prefer `expose` on newer Cypress and fall back to `env` on
+older ones:
+
+```ts
+export default defineConfig({
+  expose: {
+    pluginVisualRegressionUpdateImages: true,
+  },
+  env: {
+    pluginVisualRegressionUpdateImages: true, // fallback for Cypress < 15.10
+  },
+});
+```
+
+### References
+
+- [Cypress `Cypress.env()` migration guide](https://docs.cypress.io/app/references/migration-guide#Migrating-away-from-Cypressenv)
+- [Cypress `expose` API docs](https://on.cypress.io/expose)
+- [Issue #375](https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff/issues/375)

packages/cypress-plugin-visual-regression-diff/README.md

@@ -158,9 +158,12 @@ Still got troubles with installation? Have a look at [examples directory of this
 ## Automatic clean up of unused images
 
 It's useful to remove screenshots generated by the visual regression plugin that are not used by any test anymore.
-Enable this feature via env variable and enjoy freed up storage space 🚀:
+Enable this feature via expose variable and enjoy freed up storage space 🚀:
 
 ```bash
+# Cypress 15.10+
+npx cypress run --expose "pluginVisualRegressionCleanupUnusedImages=true"
+# Cypress <15.10 (deprecated in 15.10, removed in 16)
 npx cypress run --env "pluginVisualRegressionCleanupUnusedImages=true"
 ```
 
@@ -216,33 +219,40 @@ cy.matchImage({
 });
 ```
 
-- via [global env configuration](https://docs.cypress.io/guides/guides/environment-variables#Setting). Environment variable names are the same as keys of the configuration object above, but with added `pluginVisualRegression` prefix, e.g.:
+- via [global expose configuration](https://on.cypress.io/expose) (Cypress 15.10+). Configuration key names are the same as the keys of the configuration object above, but with added `pluginVisualRegression` prefix, e.g.:
 
 ```bash
+# Cypress 15.10+
+npx cypress run --expose "pluginVisualRegressionUpdateImages=true" --expose "pluginVisualRegressionDiffConfig={\"threshold\":0.01}"
+# Cypress <15.10 (deprecated in 15.10, removed in 16)
 npx cypress run --env "pluginVisualRegressionUpdateImages=true,pluginVisualRegressionDiffConfig={\"threshold\":0.01}"
 ```
 
 ```ts
-// cypress.config.ts
+// cypress.config.ts (Cypress 15.10+)
 import { defineConfig } from 'cypress';
 
 export default defineConfig({
-  env: {
+  expose: {
     pluginVisualRegressionUpdateImages: true,
     pluginVisualRegressionDiffConfig: { threshold: 0.01 },
   },
 });
 ```
 
-```json
-// cypress.env.json (https://docs.cypress.io/guides/guides/environment-variables#Option-2-cypress-env-json)
-{
-  "pluginVisualRegressionUpdateImages": true,
-  "pluginVisualRegressionDiffConfig": { "threshold": 0.01 }
-}
+```ts
+// cypress.config.ts (Cypress <15.10, deprecated in newer versions)
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+  env: {
+    pluginVisualRegressionUpdateImages: true,
+    pluginVisualRegressionDiffConfig: { threshold: 0.01 },
+  },
+});
 ```
 
-For more ways of setting environment variables [take a look here](https://docs.cypress.io/guides/guides/environment-variables#Setting).
+For more ways of setting expose variables [take a look here](https://on.cypress.io/expose).
 
 ## FAQ
 
@@ -269,9 +279,12 @@ This is typically caused by device pixel ratio differences between headless and
 cy.matchImage({ forceDeviceScaleFactor: true });
 ```
 
-Or set it globally via environment variable:
+Or set it globally via expose variable:
 
 ```bash
+# Cypress 15.10+
+npx cypress run --expose "pluginVisualRegressionForceDeviceScaleFactor=true"
+# Cypress <15.10 (deprecated in 15.10, removed in 16)
 npx cypress run --env "pluginVisualRegressionForceDeviceScaleFactor=true"
 ```
 
@@ -340,9 +353,12 @@ Set `maxDiffThreshold` to `0`:
 cy.matchImage({ maxDiffThreshold: 0 });
 ```
 
-Or globally via an environment variable:
+Or globally via an expose variable:
 
 ```bash
+# Cypress 15.10+
+npx cypress run --expose "pluginVisualRegressionMaxDiffThreshold=0"
+# Cypress <15.10 (deprecated in 15.10, removed in 16)
 npx cypress run --env "pluginVisualRegressionMaxDiffThreshold=0"
 ```
 

packages/cypress-plugin-visual-regression-diff/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@frsource/cypress-plugin-visual-regression-diff",
   "description": "Perform visual regression test with a nice GUI as help. 💅 Only for Cypress!",
-  "version": "4.0.2",
+  "version": "4.1.0",
   "author": "Jakub Freisler <jakub.freisler@frsource.org>",
   "homepage": "https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff",
   "repository": "https://github.com/FRSOURCE/cypress-plugin-visual-regression-diff.git",

packages/cypress-plugin-visual-regression-diff/src/commands.ts

@@ -1,4 +1,5 @@
 import { FAB_BADGE_CLASS, FILE_SUFFIX, LINK_PREFIX, TASK } from './constants';
+import { supportsExpose } from './version.utils';
 import type pixelmatch from 'pixelmatch';
 import * as Base64 from '@frsource/base64';
 import type { CompareImagesTaskReturn, PendingDiffRecord } from './types';
@@ -58,9 +59,14 @@ const constructCypressError = (log: Cypress.Log, err: Error) => {
 const capitalize = (text: string) =>
   text.charAt(0).toUpperCase() + text.slice(1);
 
-const getPluginEnv = <K extends keyof Cypress.MatchImageOptions>(key: K) =>
-  Cypress.env(`pluginVisualRegression${capitalize(key)}`) as
-    Cypress.MatchImageOptions[K] | undefined;
+const getPluginEnv = <K extends keyof Cypress.MatchImageOptions>(key: K) => {
+  const envKey = `pluginVisualRegression${capitalize(key)}`;
+  if (supportsExpose(Cypress.version)) {
+    return Cypress.expose(envKey) as Cypress.MatchImageOptions[K] | undefined;
+  }
+
+  return Cypress.env(envKey) as Cypress.MatchImageOptions[K] | undefined;
+};
 
 const booleanOption = <K extends keyof Cypress.MatchImageOptions, Return>(
   options: Cypress.MatchImageOptions,

packages/cypress-plugin-visual-regression-diff/src/plugins.test.ts

@@ -11,9 +11,10 @@ vi.mock('./afterScreenshot.hook.ts', () => ({
 }));
 
 describe('initPlugin', () => {
-  it('inits hooks', () => {
+  it('inits hooks (Cypress <15.10, env API)', () => {
     const onMock = vi.fn();
     initPlugin(onMock, {
+      version: '13.17.0',
       env: { pluginVisualRegressionForceDeviceScaleFactor: false },
     } as unknown as Cypress.PluginConfigOptions);
 
@@ -22,4 +23,18 @@ describe('initPlugin', () => {
     expect(initTaskHook).toBeCalledTimes(1);
     expect(initAfterScreenshotHook).toBeCalledTimes(1);
   });
+
+  it('inits hooks (Cypress 15.10+, expose API)', () => {
+    const onMock = vi.fn();
+    initPlugin(onMock, {
+      version: '15.10.0',
+      expose: { pluginVisualRegressionForceDeviceScaleFactor: false },
+      env: {},
+    } as unknown as Cypress.PluginConfigOptions);
+
+    expect(onMock).toBeCalledWith('task', 'task');
+    expect(onMock).toBeCalledWith('after:screenshot', 'after:screenshot');
+    expect(initTaskHook).toBeCalledTimes(2);
+    expect(initAfterScreenshotHook).toBeCalledTimes(2);
+  });
 });

packages/cypress-plugin-visual-regression-diff/src/plugins.ts

@@ -1,5 +1,6 @@
 import { initTaskHook } from './task.hook';
 import { initAfterScreenshotHook } from './afterScreenshot.hook';
+import { getPluginConfig } from './version.utils';
 
 /* c8 ignore start */
 const initForceDeviceScaleFactor = (on: Cypress.PluginEvents) => {
@@ -24,7 +25,10 @@ export const initPlugin = (
   config: Cypress.PluginConfigOptions,
 ) => {
   /* c8 ignore start */
-  if (config.env['pluginVisualRegressionForceDeviceScaleFactor'] !== false) {
+  if (
+    getPluginConfig(config, 'pluginVisualRegressionForceDeviceScaleFactor') !==
+    false
+  ) {
     initForceDeviceScaleFactor(on);
   }
   /* c8 ignore stop */