fix: improve error message when baseline is missing and both flags are false (#1099)

* fix: improve error message when baseline is missing and both flags are false

- Improve error message in checkBaselineImageExists to provide guidance
  when alwaysSaveActualImage is false and baseline doesn't exist
- Add helpful message suggesting users set alwaysSaveActualImage to true
  if they need the actual image to create a baseline
- Add test to verify the improved error message
- Respect user's explicit configuration choice (both flags set to false)

Fixes #1098

* chore: add changeset for improved error message

Author: wswebcreation

.changeset/improve-error-message-baseline.md

@@ -0,0 +1,14 @@
+---
+"@wdio/image-comparison-core": patch
+"@wdio/visual-service": patch
+---
+
+# 🐛 Bugfixes
+
+## #1098 Improve error message when baseline is missing and both flags are false
+
+When `autoSaveBaseline = false` and `alwaysSaveActualImage = false` and a baseline image doesn't exist, the error message now provides clear guidance suggesting users set `alwaysSaveActualImage` to `true` if they need the actual image to create a baseline manually.
+
+# Committers: 1
+
+-   Wim Selles ([@wswebcreation](https://github.com/wswebcreation))

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

@@ -99,7 +99,7 @@ vi.mock('./images.js', async () => {
     }
 })
 
-import { executeImageCompare } from './images.js'
+import { executeImageCompare, checkBaselineImageExists } from './images.js'
 import * as images from './images.js'
 
 describe('executeImageCompare', () => {
@@ -1091,4 +1091,46 @@ describe('executeImageCompare', () => {
         expect(images.saveBase64Image).not.toHaveBeenCalled()
         expect(fsPromises.writeFile).not.toHaveBeenCalledWith('/mock/actual/test.png', expect.anything())
     })
+
+    it('should not save actual image when baseline does not exist, alwaysSaveActualImage is false, and autoSaveBaseline is false', async () => {
+        // This test covers issue #1098: When both flags are false, we respect the user's choice
+        // and provide a helpful error message suggesting to adjust the arguments if needed
+        const base64Image = Buffer.from('base64-image').toString('base64')
+        const optionsWithoutAutoSave = {
+            ...mockOptions,
+            folderOptions: {
+                ...mockOptions.folderOptions,
+                alwaysSaveActualImage: false,
+                autoSaveBaseline: false,
+            }
+        }
+
+        vi.mocked(fsPromises.access).mockImplementation(async (path: any) => {
+            if (path === '/mock/baseline/test.png' || path === '/mock/actual/test.png') {
+                throw new Error('File not found')
+            }
+            return undefined
+        })
+
+        vi.mocked(images.checkBaselineImageExists).mockImplementation(checkBaselineImageExists)
+
+        vi.mocked(compareImages.default).mockResolvedValue({
+            rawMisMatchPercentage: 0,
+            misMatchPercentage: 0,
+            getBuffer: vi.fn().mockResolvedValue(Buffer.from('diff-image-data')),
+            diffBounds: { left: 0, top: 0, right: 0, bottom: 0 },
+            analysisTime: 10,
+            diffPixels: []
+        })
+
+        await expect(executeImageCompare({
+            isViewPortScreenshot: true,
+            isNativeContext: false,
+            options: optionsWithoutAutoSave,
+            testContext: mockTestContext,
+            actualBase64Image: base64Image,
+        })).rejects.toThrow(/If you need the actual image to create a baseline, please set alwaysSaveActualImage to true/)
+
+        expect(images.saveBase64Image).not.toHaveBeenCalled()
+    })
 })

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

@@ -107,12 +107,12 @@ export async function checkBaselineImageExists({
             const actualFileExists = await checkIfImageExists(actualFilePath)
             const filePathMessage = actualFileExists
                 ? `The image can be found here:\n${actualFilePath}`
-                : 'The actual image was not saved to disk (alwaysSaveActualImage is false).'
+                : 'The actual image was not saved to disk (alwaysSaveActualImage is false).\nIf you need the actual image to create a baseline, please set alwaysSaveActualImage to true.'
             throw new Error(
                 `
 #####################################################################################
- Baseline image not found, save the actual image manually to the baseline.
- ${filePathMessage}
+Baseline image not found, save the actual image manually to the baseline.
+${filePathMessage}
 #####################################################################################`,
             )
         }