feat: createMissingImages option

README.md

@@ -179,6 +179,9 @@ cy.matchImage({
   diffConfig: {
     threshold: 0.01,
   },
+  // whether to create missing baseline images automatically
+  // default: true
+  createMissingImages: false,
   // whether to update images automatically, without making a diff - useful for CI
   // default: false
   updateImages: true,

src/commands.ts

@@ -9,6 +9,7 @@ declare global {
     type MatchImageOptions = {
       screenshotConfig?: Partial<Cypress.ScreenshotDefaultsOptions>;
       diffConfig?: Parameters<typeof pixelmatch>[5];
+      createMissingImages?: boolean;
       updateImages?: boolean;
       /**
        * @deprecated since version 3.0, use imagesPath instead
@@ -87,6 +88,12 @@ export const getConfig = (options: Cypress.MatchImageOptions) => {
       Cypress.env("pluginVisualRegressionForceDeviceScaleFactor") === false
         ? 1
         : 1 / window.devicePixelRatio,
+    createMissingImages:
+      options.createMissingImages ||
+      (Cypress.env("pluginVisualRegressionCreateMissingImages") as
+        | boolean
+        | undefined) ||
+      true,
     updateImages:
       options.updateImages ||
       (Cypress.env("pluginVisualRegressionUpdateImages") as
@@ -125,6 +132,7 @@ Cypress.Commands.add(
 
     const {
       scaleFactor,
+      createMissingImages,
       updateImages,
       imagesPath,
       maxDiffThreshold,
@@ -178,6 +186,7 @@ Cypress.Commands.add(
               imgNew: imgPath,
               imgOld:
                 matchAgainstPath || imgPath.replace(FILE_SUFFIX.actual, ""),
+              createMissingImages,
               updateImages,
               maxDiffThreshold,
               diffConfig,

src/task.hook.test.ts

@@ -22,6 +22,7 @@ const newFileContent = "new file content";
 
 const generateConfig = async (cfg: Partial<CompareImagesCfg>) => ({
   updateImages: false,
+  createMissingImages: true,
   scaleFactor: 1,
   title: "some title",
   imgNew: await writeTmpFixture((await file()).path, newImgFixture),
@@ -48,6 +49,7 @@ describe("getScreenshotPathInfoTask", () => {
         titleFromOptions: "some-title-withśpęćiał人物",
         imagesPath: "nested/images/dir",
         specPath,
+        currentRetryNumber: 0,
       })
     ).toEqual({
       screenshotPath:
@@ -62,6 +64,7 @@ describe("getScreenshotPathInfoTask", () => {
         titleFromOptions: "some-title",
         imagesPath: "{spec_path}/images/dir",
         specPath,
+        currentRetryNumber: 0,
       })
     ).toEqual({
       screenshotPath:
@@ -76,6 +79,7 @@ describe("getScreenshotPathInfoTask", () => {
         titleFromOptions: "some-title",
         imagesPath: "/images/dir",
         specPath,
+        currentRetryNumber: 0,
       })
     ).toEqual({
       screenshotPath:
@@ -88,6 +92,7 @@ describe("getScreenshotPathInfoTask", () => {
         titleFromOptions: "some-title",
         imagesPath: "C:/images/dir",
         specPath,
+        currentRetryNumber: 0,
       })
     ).toEqual({
       screenshotPath:
@@ -104,6 +109,7 @@ describe("cleanupImagesTask", () => {
         titleFromOptions: "some-file",
         imagesPath: "images",
         specPath: "some/spec/path",
+        currentRetryNumber: 0,
       });
       return path.join(
         projectRoot,
@@ -180,6 +186,7 @@ describe("compareImagesTask", () => {
         expect(
           compareImagesTask(await generateConfig({ updateImages: true }))
         ).resolves.toEqual({
+          error: false,
           message:
             "Image diff factor (0%) is within boundaries of maximum threshold option 0.5.",
           imgDiff: 0,
@@ -198,6 +205,7 @@ describe("compareImagesTask", () => {
         await fs.unlink(cfg.imgOld);
 
         await expect(compareImagesTask(cfg)).resolves.toEqual({
+          error: false,
           message:
             "Image diff factor (0%) is within boundaries of maximum threshold option 0.5.",
           imgDiff: 0,
@@ -207,6 +215,26 @@ describe("compareImagesTask", () => {
           maxDiffThreshold: 0.5,
         });
       });
+
+      describe("when createMissingImages=false", () => {
+        it("rejects with error message", async () => {
+          const cfg = await generateConfig({
+            updateImages: false,
+            createMissingImages: false,
+          });
+          await fs.unlink(cfg.imgOld);
+
+          await expect(compareImagesTask(cfg)).resolves.toEqual({
+            error: true,
+            message: `Baseline image is missing at path: "${cfg.imgOld}". Provide a baseline image or enable "createMissingImages" option in plugin configuration.`,
+            imgDiff: 0,
+            imgDiffBase64: "",
+            imgNewBase64: "",
+            imgOldBase64: "",
+            maxDiffThreshold: 0.5,
+          });
+        });
+      });
     });
 
     describe("when old screenshot exists", () => {

src/task.hook.ts

@@ -22,6 +22,7 @@ export type CompareImagesCfg = {
   title: string;
   imgNew: string;
   imgOld: string;
+  createMissingImages: boolean;
   updateImages: boolean;
   maxDiffThreshold: number;
   diffConfig: PixelmatchOptions;
@@ -130,15 +131,6 @@ export const compareImagesTask = async (
         cfg.imgNew.replace(FILE_SUFFIX.actual, FILE_SUFFIX.diff),
         diffBuffer
       );
-      return {
-        error,
-        message: messages.join("\n"),
-        imgDiff,
-        imgNewBase64,
-        imgDiffBase64,
-        imgOldBase64,
-        maxDiffThreshold: cfg.maxDiffThreshold,
-      };
     } else {
       if (rawImgOld && !isImageCurrentVersion(rawImgOldBuffer)) {
         writePNG(cfg.imgNew, rawImgNewBuffer);
@@ -154,19 +146,30 @@ export const compareImagesTask = async (
     imgNewBase64 = "";
     imgDiffBase64 = "";
     imgOldBase64 = "";
-    writePNG(cfg.imgNew, rawImgNewBuffer);
-    moveFile.sync(cfg.imgNew, cfg.imgOld);
+    if (cfg.createMissingImages) {
+      writePNG(cfg.imgNew, rawImgNewBuffer);
+      moveFile.sync(cfg.imgNew, cfg.imgOld);
+    } else {
+      error = true;
+      messages.unshift(
+        `Baseline image is missing at path: "${cfg.imgOld}". Provide a baseline image or enable "createMissingImages" option in plugin configuration.`
+      );
+    }
   }
 
   if (typeof imgDiff !== "undefined") {
-    messages.unshift(
-      `Image diff factor (${round(
-        imgDiff
-      )}%) is within boundaries of maximum threshold option ${
-        cfg.maxDiffThreshold
-      }.`
-    );
+    if (!error) {
+      messages.unshift(
+        `Image diff factor (${round(
+          imgDiff
+        )}%) is within boundaries of maximum threshold option ${
+          cfg.maxDiffThreshold
+        }.`
+      );
+    }
+
     return {
+      error,
       message: messages.join("\n"),
       imgDiff,
       imgNewBase64,