@wdio/visual-service 9.1.2 → 9.1.4

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @wdio/visual-service
 
+## 9.1.4
+
+### Patch Changes
+
+- a3bc7a4: ## #1115 Respect `alwaysSaveActualImage: false` for `checkScreen` methods
+
+  When using visual matchers like `toMatchScreenSnapshot('tag', 0.9)` with `alwaysSaveActualImage: false`, the actual image was still being saved even when the comparison passed within the threshold.
+
+  The root cause was that the matcher's expected threshold was not being passed to the core comparison logic. The core used `saveAboveTolerance` (defaulting to 0) to decide whether to save images, while the matcher used the user-provided threshold to determine pass/fail - these were disconnected.
+
+  This fix ensures:
+
+  - When `alwaysSaveActualImage: false` and `saveAboveTolerance` is not explicitly set, actual images are never saved (respecting the literal meaning of the option)
+  - When `saveAboveTolerance` is explicitly set (like matchers do internally), actual images are saved only when the mismatch exceeds that threshold
+
+  # Committers: 1
+
+  - Wim Selles ([@wswebcreation](https://github.com/wswebcreation))
+
+- a3bc7a4: ## Fix: `save*` methods now always save files regardless of `alwaysSaveActualImage` setting
+
+  Previously, when `alwaysSaveActualImage: false` was set in the configuration, `save*` methods (`saveScreen`, `saveElement`, `saveFullPageScreen`, `saveAppScreen`, `saveAppElement`) were not saving files to disk, causing test failures.
+
+  The `alwaysSaveActualImage` option is intended to control whether actual images are saved during `check*` methods (comparison operations), not `save*` methods. Since `save*` methods are explicitly designed to save screenshots, they should always save files regardless of this setting.
+
+  This fix ensures:
+
+  - `save*` methods always save files to disk, even when `alwaysSaveActualImage: false` is set in the config
+  - `alwaysSaveActualImage: false` continues to work correctly for `check*` methods (as intended for issue #1115)
+  - The behavior is now consistent: `save*` = always save, `check*` = respect `alwaysSaveActualImage` setting
+
+  **Implementation details:**
+
+  - The visual service overrides `alwaysSaveActualImage: true` when calling `save*` methods directly from the browser API
+  - `save*` methods respect whatever `alwaysSaveActualImage` value is passed to them (no special logic needed)
+  - `check*` methods pass through the config value (which may be `false`), so `save*` methods respect it when called internally
+  - This clean separation ensures `save*` methods work correctly when called directly while still respecting `alwaysSaveActualImage` for `check*` methods
+
+  # Committers: 1
+
+  - Wim Selles ([@wswebcreation](https://github.com/wswebcreation))
+
+- Updated dependencies [a3bc7a4]
+- Updated dependencies [a3bc7a4]
+  - @wdio/image-comparison-core@1.1.3
+
+## 9.1.3
+
+### Patch Changes
+
+- 2a518ff: # 🐛 Bugfixes
+
+  ## #1111 Pass matcher threshold to core as saveAboveTolerance
+
+  When using visual matchers like `toMatchScreenSnapshot('tag', 0.9)` with `alwaysSaveActualImage: false`, the actual image was still being saved even when the comparison passed within the threshold.
+
+  The root cause was that the matcher's expected threshold was not being passed to the core comparison logic. The core used `saveAboveTolerance` (defaulting to 0) to decide whether to save images, while the matcher used the user-provided threshold to determine pass/fail - these were disconnected.
+
+  This fix ensures the matcher passes the expected threshold to the core as `saveAboveTolerance`, so images are only saved when the mismatch actually exceeds the user's acceptable threshold.
+
+  # Committers: 1
+
+  - Wim Selles ([@wswebcreation](https://github.com/wswebcreation))
+
 ## 9.1.2
 
 ### Patch Changes

package/dist/matcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,8BAA8B,EAC9B,6BAA6B,EAC7B,4BAA4B,EAC/B,MAAM,YAAY,CAAA;AAqHnB,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAC7D,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,4BAA4B;;;GAKpD;AAED,wBAAsB,uBAAuB,CACzC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAC7D,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,8BAA8B;;;GAKtD;AAED,wBAAsB,sBAAsB,CACxC,OAAO,EAAE,WAAW,CAAC,OAAO,EAC5B,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,6BAA6B;;;GAMrD;AAED,wBAAsB,2BAA2B,CAC7C,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAC7D,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,8BAA8B;;;GAKtD"}
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../src/matcher.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACR,8BAA8B,EAC9B,6BAA6B,EAC7B,4BAA4B,EAC/B,MAAM,YAAY,CAAA;AAwInB,wBAAsB,qBAAqB,CACvC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAC7D,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,4BAA4B;;;GAKpD;AAED,wBAAsB,uBAAuB,CACzC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAC7D,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,8BAA8B;;;GAKtD;AAED,wBAAsB,sBAAsB,CACxC,OAAO,EAAE,WAAW,CAAC,OAAO,EAC5B,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,6BAA6B;;;GAMrD;AAED,wBAAsB,2BAA2B,CAC7C,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAC7D,GAAG,EAAE,MAAM,EACX,uBAAuB,CAAC,EAAE,MAAM,GAAG,iBAAiB,CAAC,cAAc,CAAC,MAAM,CAAC,EAC3E,kBAAkB,CAAC,EAAE,8BAA8B;;;GAKtD"}

package/dist/matcher.js

@@ -82,6 +82,25 @@ function parseMatcherParams(tag, expectedResult, options) {
      * overwrite `returnAllCompareData` to allow us to provide a better assertion message
      */
     options.returnAllCompareData = true;
+    /**
+     * Pass the expected threshold to the core as `saveAboveTolerance` so it knows
+     * when to save actual images (only when mismatch exceeds the threshold).
+     * This ensures that when `alwaysSaveActualImage: false`, images are not saved
+     * if the comparison passes within the user's acceptable threshold.
+     * Only set if user hasn't explicitly set saveAboveTolerance.
+     * For numeric thresholds, use that value; otherwise default to 0 (same as comparison default).
+     * @see https://github.com/webdriverio/visual-testing/issues/1111
+     */
+    if (options.saveAboveTolerance === undefined) {
+        // Only set saveAboveTolerance for numeric thresholds (including undefined which defaults to 0)
+        // Asymmetric matchers can't be converted to a numeric tolerance
+        if (typeof expectedResult === 'number') {
+            options.saveAboveTolerance = expectedResult;
+        }
+        else if (expectedResult === undefined) {
+            options.saveAboveTolerance = DEFAULT_EXPECTED_RESULT;
+        }
+    }
     return { expectedResult, options };
 }
 export async function toMatchScreenSnapshot(browser, tag, expectedResultOrOptions, optionsOrUndefined) {

package/dist/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EACH,SAAS,EAWZ,MAAM,6BAA6B,CAAA;AAiBpC,OAAO,KAAK,EAAc,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAepD,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,SAAS;;IAM7D,OAAO,CAAC,eAAe,CAAC,CAAgB;IACxC,OAAO,CAAC,gBAAgB,CAAC,CAAyC;gBAEtD,OAAO,EAAE,oBAAoB,EAAE,CAAC,EAAE,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM;IAMlG;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB;IAIzE,MAAM,CACR,YAAY,EAAE,WAAW,CAAC,YAAY,EACtC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB;IAgC3D,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI;IAOtC,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK;IA4ZtC,IAAI,cAAc,IAAI,cAAc,CAKnC;CAyCJ"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,UAAU,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EACH,SAAS,EAWZ,MAAM,6BAA6B,CAAA;AAiBpC,OAAO,KAAK,EAAc,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAepD,MAAM,CAAC,OAAO,OAAO,0BAA2B,SAAQ,SAAS;;IAM7D,OAAO,CAAC,eAAe,CAAC,CAAgB;IACxC,OAAO,CAAC,gBAAgB,CAAC,CAAyC;gBAEtD,OAAO,EAAE,oBAAoB,EAAE,CAAC,EAAE,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM;IAMlG;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB;IAIzE,MAAM,CACR,YAAY,EAAE,WAAW,CAAC,YAAY,EACtC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,WAAW,CAAC,OAAO,GAAG,WAAW,CAAC,kBAAkB;IAgC3D,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI;IAOtC,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,KAAK;IAwatC,IAAI,cAAc,IAAI,cAAc,CAKnC;CAyCJ"}

package/dist/service.js

@@ -162,6 +162,11 @@ export default class WdioImageComparisonService extends BaseClass {
                         deviceRectangles: self.contextManager.getViewportContext(),
                     };
                     const isCurrentContextNative = self.contextManager.isNativeContext;
+                    // save* methods should always save files, regardless of alwaysSaveActualImage config
+                    const isSaveCommand = commandName === 'saveElement';
+                    const wicOptions = isSaveCommand
+                        ? { ...self.defaultOptions, alwaysSaveActualImage: true }
+                        : self.defaultOptions;
                     return [{
                             browserInstance,
                             element,
@@ -170,7 +175,7 @@ export default class WdioImageComparisonService extends BaseClass {
                             isNativeContext: isCurrentContextNative,
                             tag,
                             [elementOptionsKey]: {
-                                wic: self.defaultOptions,
+                                wic: wicOptions,
                                 method: elementOptions,
                             },
                             testContext: enrichTestContext({
@@ -207,6 +212,11 @@ export default class WdioImageComparisonService extends BaseClass {
                         deviceRectangles: self.contextManager.getViewportContext()
                     };
                     const isCurrentContextNative = self.contextManager.isNativeContext;
+                    // save* methods should always save files, regardless of alwaysSaveActualImage config
+                    const isSaveCommand = commandName === 'saveScreen' || commandName === 'saveFullPageScreen' || commandName === 'saveTabbablePage';
+                    const wicOptions = isSaveCommand
+                        ? { ...self.defaultOptions, alwaysSaveActualImage: true }
+                        : self.defaultOptions;
                     return [{
                             browserInstance,
                             folders: getFolders(pageOptions, self.folders, self.#getBaselineFolder()),
@@ -214,7 +224,7 @@ export default class WdioImageComparisonService extends BaseClass {
                             isNativeContext: isCurrentContextNative,
                             tag,
                             [pageOptionsKey]: {
-                                wic: self.defaultOptions,
+                                wic: wicOptions,
                                 method: pageOptions,
                             },
                             testContext: enrichTestContext({

package/package.json

@@ -2,7 +2,7 @@
   "name": "@wdio/visual-service",
   "author": "Wim Selles - wswebcreation",
   "description": "Image comparison / visual regression testing for WebdriverIO",
-  "version": "9.1.2",
+  "version": "9.1.4",
   "license": "MIT",
   "homepage": "https://webdriver.io/docs/visual-testing",
   "repository": {
@@ -24,7 +24,7 @@
     "@wdio/logger": "^9.18.0",
     "@wdio/types": "^9.20.0",
     "expect-webdriverio": "^5.6.1",
-    "@wdio/image-comparison-core": "1.1.2"
+    "@wdio/image-comparison-core": "1.1.3"
   },
   "scripts": {
     "build": "run-s clean build:*",