feat: add matchAgainstPath option (#146)

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

closes #88
BREAKING CHANGE: matchImage returns object containing comparison details from now on (previously was returning subject element from a chain)

Author: FRSgit

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'
 })
 ```
 

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 });
+      })
   })
 })

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,
+        }
       });
   }
 );