From 6d3b58a90111c27eea4b77c5ad1a002012cfdfee Mon Sep 17 00:00:00 2001
From: Jakub Freisler <jakub@frsource.org>
Date: Wed, 12 Oct 2022 04:14:03 +0200
Subject: [PATCH] feat: add matchAgainstPath option

allow to compare screenshots against custom reference images
add docs
add example test case

BREAKING CHANGE: matchImage returns object containing comparison details from now on (previously was rereturning subject from a chain)

Signed-off-by: Jakub Freisler <jakub@frsource.org>
---
 README.md                      |  4 ++++
 example/cypress/e2e/spec.cy.js |  4 ++++
 src/commands.ts                | 41 +++++++++++++++++++++++++++++-----
 3 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index c9885ef7..90315dc3 100644
--- a/README.md
+++ b/README.md
@@ -178,6 +178,10 @@ cy.matchImage({
   // title used for naming the image file
   // default: Cypress.currentTest.titlePath (your test title)
   title: `${Cypress.currentTest.titlePath.join(' ')} (${Cypress.browser.displayName})`
+  // pass a path to custom image that should be used for comparison
+  // instead of checking against the image from previous run
+  // default: undefined
+  matchAgainstPath: '/path/to/reference-image.png'
 })
 ```
 
diff --git a/example/cypress/e2e/spec.cy.js b/example/cypress/e2e/spec.cy.js
index 8e41043d..4671caf8 100644
--- a/example/cypress/e2e/spec.cy.js
+++ b/example/cypress/e2e/spec.cy.js
@@ -3,5 +3,9 @@ describe('My First Test', () => {
     cy.visit('/')
     cy.contains('h1', 'Welcome to Your Vue.js App')
     cy.matchImage()
+      .then(({ imgNewPath }) => {
+        // match against image from custom path
+        cy.matchImage({ matchAgainstPath: imgNewPath });
+      })
   })
 })
diff --git a/src/commands.ts b/src/commands.ts
index 1cf24c3e..f8197e0f 100644
--- a/src/commands.ts
+++ b/src/commands.ts
@@ -13,6 +13,22 @@ declare global {
       imagesDir?: string;
       maxDiffThreshold?: number;
       title?: string;
+      matchAgainstPath?: string;
+      // IDEA: to be implemented if support for files NOT from filesystem needed
+      // matchAgainst?: string | Buffer;
+    };
+
+    type MatchImageReturn = {
+      diffValue: number | undefined;
+      imgNewPath: string;
+      imgPath: string;
+      imgDiffPath: string;
+      imgNewBase64: string | undefined;
+      imgBase64: string | undefined;
+      imgDiffBase64: string | undefined;
+      imgNew: InstanceType<Cypress['Buffer']> | undefined;
+      img: InstanceType<Cypress['Buffer']> | undefined;
+      imgDiff: InstanceType<Cypress['Buffer']> | undefined;
     };
 
     interface Chainable<Subject> {
@@ -21,7 +37,7 @@ declare global {
        * @memberof Cypress.Chainable
        * @example cy.get('.my-element').matchImage();
        */
-      matchImage(options?: Cypress.MatchImageOptions): Chainable<Subject>;
+      matchImage(options?: Cypress.MatchImageOptions): Chainable<MatchImageReturn>;
     }
   }
 }
@@ -69,6 +85,7 @@ export const getConfig = (options: Cypress.MatchImageOptions) => ({
       | Partial<Cypress.ScreenshotDefaultsOptions>
       | undefined) ||
     {},
+  matchAgainstPath: options.matchAgainstPath ||  undefined,
 });
 
 Cypress.Commands.add(
@@ -88,6 +105,7 @@ Cypress.Commands.add(
       maxDiffThreshold,
       diffConfig,
       screenshotConfig,
+      matchAgainstPath,
     } = getConfig(options);
 
     return cy
@@ -115,14 +133,14 @@ Cypress.Commands.add(
           })
           .then(() => imgPath);
       })
-      .then((imgPath) =>
-        cy
+      .then((imgPath) => {
+        return cy
           .task<CompareImagesTaskReturn>(
             TASK.compareImages,
             {
               scaleFactor,
               imgNew: imgPath,
-              imgOld: imgPath.replace(FILE_SUFFIX.actual, ""),
+              imgOld: matchAgainstPath || imgPath.replace(FILE_SUFFIX.actual, ""),
               updateImages,
               maxDiffThreshold,
               diffConfig,
@@ -133,7 +151,7 @@ Cypress.Commands.add(
             res,
             imgPath,
           }))
-      )
+      })
       .then(({ res, imgPath }) => {
         const log = Cypress.log({
           name: "log",
@@ -170,6 +188,19 @@ Cypress.Commands.add(
           log.set("consoleProps", () => res);
           throw constructCypressError(log, new Error(res.message));
         }
+
+        return {
+          diffValue: res.imgDiff,
+          imgNewPath: imgPath,
+          imgPath: imgPath.replace(FILE_SUFFIX.actual, ""),
+          imgDiffPath: imgPath.replace(FILE_SUFFIX.actual, FILE_SUFFIX.diff),
+          imgNewBase64: res.imgNewBase64,
+          imgBase64: res.imgOldBase64,
+          imgDiffBase64: res.imgDiffBase64,
+          imgNew: typeof res.imgNewBase64 === 'string' ? Cypress.Buffer.from(res.imgNewBase64, 'base64') : undefined,
+          img: typeof res.imgOldBase64 === 'string' ? Cypress.Buffer.from(res.imgOldBase64, 'base64') : undefined,
+          imgDiff: typeof res.imgDiffBase64 === 'string' ? Cypress.Buffer.from(res.imgDiffBase64, 'base64') : undefined,
+        }
       });
   }
 );