Add support for accessing detailed test info via toMatchSnapshot callback (#83)

* [#82] Add support for accessing detailed test values via toMatchSnapshot

Updates `toMatchSnapshot` to accept a second argument, a callback. Upon
evaluation of the test, the test result is set on the class instance. If
`toMatchSnapshot` is given a callback, the callback is invoked upon
completion of the test and passed the full result data.

- Include additional test result data in return for verbosity
- Store result on instance and invoke callback with data if present
- Add verbosity to error and success return values

* [#82] Update tests and documentation to reflect toMatchSnapshot changes

* [#82] Add description of arguments for toMatchSnapshot

Author: EranSch

API.md

@@ -11,7 +11,7 @@
 
 |Method|Arguments|description|
 |------|---------|-----------|
-|`toMatchSnapshot`|no argument|It matches the captured screenshot with reference screenshot|
+|`toMatchSnapshot`|`image` or <br /> `image, callback` or <br />` callback` | Pass an image object to compare it to the snapshot. Optionally, pass a callback to receive [details from the comparison](#detailed-result-information). Alternatively, just pass a callback to receive details of the snapshot currently in the chain. |
 |`result`|`Object`|A function that returns response object of previous step when on chained mode|
 |`launch`|`Object` [puppeteer.launch options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions)|launches new browser and returns browser object|
 |`connect`|`Object` [puppeteer.connect options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerconnectoptions)|Attaches to an existing browser instance and returns browser object|
@@ -167,6 +167,88 @@ In this example, differencify will launch a browser instance and share same brow
 ```
 In this example, after calling `result` function it will return the previous step result as an object.
 
+## Detailed Result Information
+
+For programmatic use cases where more information is required than simply whether or not
+a test passed, a callback function may be passed to `toMatchSnapshot` which will be invoked
+after the test and passed additional details.
+
+```js
+(async () => {
+  await differencify
+    .init()
+    .newPage()
+    .setViewport({ width: 1600, height: 1200 })
+    .goto('https://github.com/NimaSoroush/differencify')
+    .screenshot()
+    .toMatchSnapshot((resultDetail) => {
+     console.log(resultDetail);
+     /*
+     Example output:
+      {
+        testConfig: {
+          chain: false,
+          testNameProvided: true,
+          testName: 'TestName',
+          'testId': 2,
+          'isUpdate': false,
+          'isJest': false,
+          'newWindow': true
+        },
+        testResult: {
+          diffPath: '/parent/__image_snapshots__/__differencified_output__/test.differencified.png',
+          matched: false,
+          diffPercent: 0.02,
+          distance: 0,
+          snapshotPath: '/parent/__image_snapshots__/test.snap.png',
+        }
+      }
+    */
+    })
+    .close()
+    .end();
+})();
+```
+
+Similarly, the callback may be passed as a second argument when unchained:
+
+```js
+(async () => {
+  const target = differencify.init({ chain: false });
+  await target.launch();
+  const page = await target.newPage();
+  await page.goto('https://github.com/NimaSoroush/differencify');
+  await page.setViewport({ width: 1600, height: 1200 });
+  await page.waitFor(1000);
+  const image = await page.screenshot();
+  await target.toMatchSnapshot(image, (resultDetail) => {
+   console.log(resultDetail);
+   /*
+   Example output:
+    {
+      testConfig: {
+        chain: false,
+        testNameProvided: true,
+        testName: 'TestName',
+        'testId': 2,
+        'isUpdate': false,
+        'isJest': false,
+        'newWindow': true
+      },
+      testResult: {
+        diffPath: '/parent/__image_snapshots__/__differencified_output__/test.differencified.png',
+        matched: false,
+        diffPercent: 0.02,
+        distance: 0,
+        snapshotPath: '/parent/__image_snapshots__/test.snap.png',
+      }
+    }
+  */
+  });
+  await page.close();
+  await target.close();
+})();
+```
 
 ## Context switching when chained
 

src/compareImage.js

@@ -45,22 +45,22 @@ const compareImage = async (capturedImage, globalConfig, testConfig) => {
     } catch (error) {
       prefixedLogger.error(`failed to read reference image: ${snapshotPath}`);
       prefixedLogger.trace(error);
-      return { matched: false };
+      return { error: 'Failed to read reference image', matched: false };
     }
     let testImage;
     try {
       testImage = await Jimp.read(capturedImage);
     } catch (error) {
       prefixedLogger.error('failed to read current screenshot image');
       prefixedLogger.trace(error);
-      return { matched: false };
+      return { error: 'Failed to read current screenshot image', matched: false };
     }
     prefixedLogger.log('comparing...');
     const distance = Jimp.distance(snapshotImage, testImage);
     const diff = Jimp.diff(snapshotImage, testImage, globalConfig.mismatchThreshold);
     if (distance < globalConfig.mismatchThreshold && diff.percent < globalConfig.mismatchThreshold) {
       prefixedLogger.log('no mismatch found ✅');
-      return { matched: true };
+      return { snapshotPath, distance, diffPercent: diff.percent, matched: true };
     }
     if (globalConfig.saveDifferencifiedImage) {
       try {
@@ -84,7 +84,7 @@ const compareImage = async (capturedImage, globalConfig, testConfig) => {
         diff: ${diff.percent}
         misMatchThreshold: ${globalConfig.mismatchThreshold}
     `);
-    return { diffPath, matched: false };
+    return { snapshotPath, distance, diffPercent: diff.percent, diffPath, matched: false };
   }
   prefixedLogger.log(`screenshot saved in -> ${snapshotPath}`);
   if (fs.existsSync(diffPath)) {

src/compareImage.test.js

@@ -130,7 +130,10 @@ describe('Compare Image', () => {
     Jimp.read.mockReturnValueOnce(Promise.reject('error1'));
     fs.existsSync.mockReturnValueOnce(true);
     const result = await compareImage(Object, mockConfig, mockTestConfig);
-    expect(result).toEqual({ matched: false });
+    expect(result).toEqual({
+      error: 'Failed to read reference image',
+      matched: false,
+    });
     expect(mockTrace).toHaveBeenCalledWith('error1');
     expect(mockError).toHaveBeenCalledWith('failed to read reference image: /parent/__image_snapshots__/test.snap.png');
   });
@@ -139,7 +142,12 @@ describe('Compare Image', () => {
     expect.assertions(2);
     fs.existsSync.mockReturnValueOnce(true);
     const result = await compareImage(Object, mockConfig, mockTestConfig);
-    expect(result).toEqual({ matched: true });
+    expect(result).toEqual({
+      diffPercent: 0,
+      distance: 0,
+      matched: true,
+      snapshotPath: '/parent/__image_snapshots__/test.snap.png',
+    });
     expect(mockLog).toHaveBeenCalledWith('no mismatch found ✅');
   });
 
@@ -157,6 +165,9 @@ describe('Compare Image', () => {
     expect(result).toEqual({
       diffPath: '/parent/__image_snapshots__/__differencified_output__/test.differencified.png',
       matched: false,
+      diffPercent: 0.02,
+      distance: 0,
+      snapshotPath: '/parent/__image_snapshots__/test.snap.png',
     });
     expect(mockError).toHaveBeenCalledWith(`mismatch found❗
       Result:
@@ -181,6 +192,9 @@ describe('Compare Image', () => {
     expect(result).toEqual({
       diffPath: '/parent/__image_snapshots__/__differencified_output__/test.differencified.png',
       matched: false,
+      diffPercent: 0,
+      distance: 0.02,
+      snapshotPath: '/parent/__image_snapshots__/test.snap.png',
     });
     expect(mockError).toHaveBeenCalledWith(`mismatch found❗
       Result:
@@ -205,6 +219,9 @@ describe('Compare Image', () => {
     expect(result).toEqual({
       diffPath: '/parent/__image_snapshots__/__differencified_output__/test.differencified.png',
       matched: false,
+      diffPercent: 0.02,
+      distance: 0.02,
+      snapshotPath: '/parent/__image_snapshots__/test.snap.png',
     });
     expect(mockError).toHaveBeenCalledWith(`mismatch found❗
       Result:
@@ -234,6 +251,9 @@ describe('Compare Image', () => {
     expect(result).toEqual({
       diffPath: '/parent/__image_snapshots__/__differencified_output__/test.differencified.png',
       matched: false,
+      diffPercent: 0.02,
+      distance: 0.02,
+      snapshotPath: '/parent/__image_snapshots__/test.snap.png',
     });
     expect(mockWrite)
       .toHaveBeenCalledWith('/parent/__image_snapshots__/__differencified_output__/test.differencified.png',

src/integration.tests/__image_snapshots__/Differencify Using toMatchSnapshot callback for result details when unchained.snap.png

@@ -74,6 +74,70 @@ describe('Differencify', () => {
       .close()
       .end();
   }, 30000);
+  it('Using toMatchSnapshot callback for result details', async () => {
+    await differencify
+      .init()
+      .newPage()
+      .setViewport({ width: 1600, height: 1200 })
+      .goto('http://example.com/')
+      .waitFor(1000)
+      .title()
+      .screenshot()
+      .toMatchSnapshot((resultDetail) => {
+        expect(resultDetail).toEqual({
+          testConfig: {
+            chain: true,
+            imageType: 'png',
+            isJest: true,
+            isUpdate: false,
+            testId: 6,
+            testName: 'Differencify Using toMatchSnapshot callback for result details',
+            testNameProvided: false,
+            testPath: '/differencify/src/integration.tests/integration.test.js',
+          },
+          testResult: {
+            diffPercent: 0,
+            distance: 0,
+            matched: true,
+            snapshotPath: '/differencify/src/integration.tests/__image_snapshots__/Differencify Using toMatchSnapshot callback for result details.snap.png',
+          },
+        });
+      })
+      .close()
+      .end();
+  }, 30000);
+  it('Using toMatchSnapshot callback for result details when unchained', async () => {
+    const target = differencify.init({ chain: false });
+    await target.launch({ args: ['--no-sandbox', '--disable-setuid-sandbox'] });
+    const page = await target.newPage();
+    await page.goto('http://example.com/');
+    await page.setViewport({ width: 1600, height: 1200 });
+    await page.waitFor(1000);
+    const image = await page.screenshot();
+    await target.toMatchSnapshot(image, (resultDetail) => {
+      expect(resultDetail).toEqual({
+        testConfig: {
+          chain: false,
+          imageType: undefined,
+          isJest: true,
+          isUpdate: false,
+          newWindow: true,
+          testId: 7,
+          testName: 'Differencify Using toMatchSnapshot callback for result details when unchained',
+          testNameProvided: false,
+          testPath: '/differencify/src/integration.tests/integration.test.js',
+        },
+        testResult: {
+          diffPercent: 0,
+          distance: 0,
+          matched: true,
+          snapshotPath: '/differencify/src/integration.tests/__image_snapshots__/Differencify Using toMatchSnapshot callback for result details when unchained.snap.png',
+        },
+      });
+    });
+    await page.close();
+    await target.close();
+  }, 30000);
   it('Context switching when chained', async () => {
     await differencify
       .init()

src/integration.tests/__image_snapshots__/Differencify Using toMatchSnapshot callback for result details.snap.png

@@ -18,6 +18,7 @@ export default class Target {
     this.error = null;
     this.image = null;
     this.testId = 0;
+    this.result = null;
   }
 
   _logError(error) {
@@ -199,9 +200,15 @@ export default class Target {
     }
   }
 
-  async toMatchSnapshot(image) {
-    if (image) {
+  async toMatchSnapshot(image, callback) {
+    let resultCallback;
+    if (image && !isFunc(image)) {
       this.image = image;
+    } else if (isFunc(image)) {
+      resultCallback = image;
+    }
+    if (callback && isFunc(callback)) {
+      resultCallback = callback;
     }
     if (this.testConfig.isJest && !this.testConfig.testNameProvided) {
       this.testConfig.testName = this.testId
@@ -213,14 +220,20 @@ export default class Target {
         : this.testConfig.testName;
     }
     this.testId += 1;
-    return await this._evaluateResult();
+    const result = await this._evaluateResult();
+    if (resultCallback) {
+      resultCallback({
+        testConfig: this.testConfig,
+        testResult: this.result,
+      });
+    }
+    return result;
   }
 
   async _evaluateResult() {
     if (!this.error) {
-      let result;
       try {
-        result = await compareImage(this.image, this.globalConfig, this.testConfig);
+        this.result = await compareImage(this.image, this.globalConfig, this.testConfig);
       } catch (error) {
         this._logError(error);
       }
@@ -230,9 +243,9 @@ export default class Target {
       if (this.testConfig.isJest === true) {
         const toMatchImageSnapshot = jestMatchers.toMatchImageSnapshot;
         expect.extend({ toMatchImageSnapshot });
-        expect(result).toMatchImageSnapshot(this.testStats);
+        expect(this.result).toMatchImageSnapshot(this.testStats);
       }
-      if (result.matched || result.updated || result.added) {
+      if (this.result.matched || this.result.updated || this.result.added) {
         return true;
       }
     }