fix: alwaysSaveActualImage: false does not respect comparison threshold larger than 0

Fixes #1111

When `alwaysSaveActualImage` is `false`, the actual image is no longer written to disk if the mismatch is below the configured tolerance, avoiding extra actuals when the comparison still passes.

Author: wswebcreation

.changeset/smooth-berries-fix.md

@@ -0,0 +1,12 @@
+---
+"@wdio/image-comparison-core": patch
+"@wdio/visual-service": patch
+---
+
+## #1111 Respect saveAboveTolerance when deciding to save actual images when alwaysSaveActualImage is false.
+
+When `alwaysSaveActualImage` is `false`, the actual image is no longer written to disk if the mismatch is below the configured tolerance, avoiding extra actuals when the comparison still passes.
+
+# Committers: 1
+
+- Wim Selles ([@wswebcreation](https://github.com/wswebcreation))

packages/image-comparison-core/src/methods/images.executeImageCompare.test.ts

@@ -722,6 +722,78 @@ describe('executeImageCompare', () => {
         expect(fsPromises.writeFile).toHaveBeenCalledWith('/mock/actual/test.png', Buffer.from(base64Image, 'base64'))
     })
 
+    it('should not save base64 actual when diff is below saveAboveTolerance', async () => {
+        const base64Image = Buffer.from('base64-image').toString('base64')
+        const optionsWithTolerance = {
+            ...mockOptions,
+            folderOptions: {
+                ...mockOptions.folderOptions,
+                alwaysSaveActualImage: false,
+            },
+            compareOptions: {
+                ...mockOptions.compareOptions,
+                wic: {
+                    ...mockOptions.compareOptions.wic,
+                    saveAboveTolerance: 0.1,
+                },
+            },
+        }
+        vi.mocked(compareImages.default).mockResolvedValue({
+            rawMisMatchPercentage: 0.05,
+            misMatchPercentage: 0.05,
+            getBuffer: vi.fn().mockResolvedValue(Buffer.from('diff-image-data')),
+            diffBounds: { left: 0, top: 0, right: 0, bottom: 0 },
+            analysisTime: 10,
+            diffPixels: []
+        })
+
+        await executeImageCompare({
+            isViewPortScreenshot: true,
+            isNativeContext: false,
+            options: optionsWithTolerance,
+            testContext: mockTestContext,
+            actualBase64Image: base64Image,
+        })
+
+        expect(fsPromises.writeFile).not.toHaveBeenCalled()
+    })
+
+    it('should save base64 actual when diff exceeds saveAboveTolerance', async () => {
+        const base64Image = Buffer.from('base64-image').toString('base64')
+        const optionsWithTolerance = {
+            ...mockOptions,
+            folderOptions: {
+                ...mockOptions.folderOptions,
+                alwaysSaveActualImage: false,
+            },
+            compareOptions: {
+                ...mockOptions.compareOptions,
+                wic: {
+                    ...mockOptions.compareOptions.wic,
+                    saveAboveTolerance: 0.1,
+                },
+            },
+        }
+        vi.mocked(compareImages.default).mockResolvedValue({
+            rawMisMatchPercentage: 0.2,
+            misMatchPercentage: 0.2,
+            getBuffer: vi.fn().mockResolvedValue(Buffer.from('diff-image-data')),
+            diffBounds: { left: 0, top: 0, right: 0, bottom: 0 },
+            analysisTime: 10,
+            diffPixels: []
+        })
+
+        await executeImageCompare({
+            isViewPortScreenshot: true,
+            isNativeContext: false,
+            options: optionsWithTolerance,
+            testContext: mockTestContext,
+            actualBase64Image: base64Image,
+        })
+
+        expect(fsPromises.writeFile).toHaveBeenCalledWith('/mock/actual/test.png', Buffer.from(base64Image, 'base64'))
+    })
+
     it('should update baseline using base64 when visual baseline is updated', async () => {
         const base64Image = Buffer.from('base64-image').toString('base64')
         vi.mocked(utils.updateVisualBaseline).mockReturnValueOnce(true)

packages/image-comparison-core/src/methods/images.ts

@@ -451,7 +451,7 @@ export async function executeImageCompare(
 
     // 6a. Save actual image on failure if alwaysSaveActualImage is false
     const saveAboveTolerance = imageCompareOptions.saveAboveTolerance ?? 0
-    const hasFailure = rawMisMatchPercentage > 0 || rawMisMatchPercentage > saveAboveTolerance
+    const hasFailure = rawMisMatchPercentage > saveAboveTolerance
     if (useBase64Image && hasFailure && actualBase64Image) {
         // Save the actual image only when comparison fails
         await saveBase64Image(actualBase64Image, actualFilePath)