Improve error message when baseline is missing and both autoSaveBaseline and alwaysSaveActualImage are false

[wswebcreation]

Improve error message when baseline is missing and both autoSaveBaseline and alwaysSaveActualImage are false

Problem

When autoSaveBaseline = false and alwaysSaveActualImage = false and a baseline image doesn't exist, the following happens:

1. The actual image is not saved to disk (which is correct - the user explicitly set both flags to false)
2. An error is thrown: "Baseline image not found, save the actual image manually to the baseline."
3. The error message states: "The actual image was not saved to disk (alwaysSaveActualImage is false)."

The current error message doesn't provide clear guidance on how to resolve the situation. Users might not understand that they need to adjust their configuration to get the actual image saved.

Current Behavior

Code location: packages/image-comparison-core/src/methods/images.ts

Line 387-390 in executeImageCompare:

// Only save actual image if baseline doesn't exist and autoSaveBaseline is true
if (autoSaveBaseline && !(await checkIfImageExists(baselineFilePath))) {
    await saveBase64Image(actualBase64Image, actualFilePath)
}

Line 105-117 in checkBaselineImageExists:

} else {
    // Check if actual file exists before referencing it in error message
    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).'
    throw new Error(
        `
#####################################################################################
Baseline image not found, save the actual image manually to the baseline.
${filePathMessage}
#####################################################################################`,
    )
}

Analysis

The current behavior is correct. When both autoSaveBaseline = false and alwaysSaveActualImage = false, we should respect the user's explicit configuration choice and not save the actual image. This is by design - the user has told the system not to save images in this scenario.

However, the error message could be more helpful by guiding users on how to adjust their configuration if they need the actual image to create a baseline manually.

Proposed Solution

Improve the error message to provide clear guidance on how to resolve the situation:

Proposed change in checkBaselineImageExists (around line 110):

const filePathMessage = actualFileExists
    ? `The image can be found here:\n${actualFilePath}`
    : '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.'

Benefits

• ✅ Respects user's explicit configuration choice (both flags set to false)
• ✅ Provides clear guidance on how to adjust configuration if needed
• ✅ Better user experience with actionable error messages
• ✅ No breaking changes to existing behavior

Rationale

When a user explicitly sets both autoSaveBaseline = false and alwaysSaveActualImage = false, they are making a conscious choice not to save images. We should respect this choice. However, we can improve the error message to help users understand how to adjust their configuration if they realize they need the actual image after all.

Implementation

The fix has been implemented in:

• packages/image-comparison-core/src/methods/images.ts - checkBaselineImageExists function (line 110)
• Test added in packages/image-comparison-core/src/methods/images.executeImageCompare.test.ts to verify the improved error message

Related Code

• packages/image-comparison-core/src/methods/images.ts - executeImageCompare function (lines 380-402)
• packages/image-comparison-core/src/methods/images.ts - checkBaselineImageExists function (lines 66-120)

[wswebcreation]

closing it in favor oof #1099