Showing reference and current images along with the diff result

docs/configuration.md

@@ -58,6 +58,10 @@ There are three currently available options to choose from when comparing images
 }
 ```
 
+### `includeReferenceOnDiff`
+
+This property enables combining the diff with the reference images, side by side. This allows for a better visualization of the previous state and the new one, along with the diff engine result.
+
 ### [`pixelmatch`](https://github.com/mapbox/pixelmatch)
 
 The default engine and is JavaScript only. It's more sensitive to changes on large images and is less susceptible to anti alias flakiness.

packages/diff-pixelmatch/src/create-pixelmatch-differ.js

@@ -20,7 +20,7 @@ const resizeImage = (original, width, height) => {
   return resized;
 };
 
-function createPixelmatchDiffer(config) {
+function createPixelmatchDiffer(config, includeReferenceOnDiff = false) {
   return async function getImageDiff(path1, path2, diffPath, tolerance) {
     let [reference, current] = await Promise.all([
       fs.readFile(path1),
@@ -62,7 +62,15 @@ function createPixelmatchDiffer(config) {
     );
     const isEqual = numDiffPixels === 0;
     if (!isEqual) {
-      await fs.outputFile(diffPath, PNG.sync.write(diff));
+      if (!includeReferenceOnDiff) {
+        await fs.outputFile(diffPath, PNG.sync.write(diff));
+      } else {
+        const diffCombined = new PNG({ width: width * 3, height });
+        PNG.bitblt(reference, diffCombined, 0, 0, width, height, width * 0);
+        PNG.bitblt(current, diffCombined, 0, 0, width, height, width * 1);
+        diff.bitblt(diffCombined, 0, 0, width, height, width * 2);
+        await fs.outputFile(diffPath, PNG.sync.write(diffCombined));
+      }
     }
     return isEqual;
   };

packages/diff-pixelmatch/src/create-pixelmatch-differ.spec.js

@@ -1,5 +1,6 @@
 const fs = require('fs-extra');
 const path = require('path');
+const { PNG } = require('pngjs');
 const createPixelmatchDiffer = require('./create-pixelmatch-differ');
 
 const workingDirectory = `./pixelmatch-${Math.round(Math.random() * 1000)}`;
@@ -15,12 +16,14 @@ function writeBase64Image({ outputPath, base64String }) {
 
 describe('createPixelmatchDiffer', () => {
   beforeEach(() => {
+    // 1x1 png picture
     const darkGrayBase64String =
       'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQYV2NISUn5DwAEiAIshLJN6AAAAABJRU5ErkJggg==';
     writeBase64Image({
       outputPath: darkGrayPath,
       base64String: darkGrayBase64String,
     });
+    // 1x1 png picture
     const lightGrayBase64String =
       'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQYV2M4ceLEfwAIDANYMDoQswAAAABJRU5ErkJggg==';
     writeBase64Image({
@@ -48,4 +51,33 @@ describe('createPixelmatchDiffer', () => {
 
     expect(fs.existsSync(diffPath)).toEqual(true);
   });
+
+  it('should output only the diff image by default', async () => {
+    const config = {};
+    const diffPath = path.join(workingDirectory, 'diff.png');
+    const pixelmatchDiffer = createPixelmatchDiffer(config);
+    const tolerance = 0;
+    await pixelmatchDiffer(darkGrayPath, lightGrayPath, diffPath, tolerance);
+    const outputPNG = PNG.sync.read(fs.readFileSync(diffPath));
+    expect(outputPNG).toEqual(
+      expect.objectContaining({
+        width: 1,
+        height: 1,
+      })
+    );
+  });
+  it('should be able to save the image with previous and current version along with diff', async () => {
+    const config = {};
+    const diffPath = path.join(workingDirectory, 'diff.png');
+    const pixelmatchDiffer = createPixelmatchDiffer(config, true);
+    const tolerance = 0;
+    await pixelmatchDiffer(darkGrayPath, lightGrayPath, diffPath, tolerance);
+    const outputPNG = PNG.sync.read(fs.readFileSync(diffPath));
+    expect(outputPNG).toEqual(
+      expect.objectContaining({
+        width: 3,
+        height: 1,
+      })
+    );
+  });
 });

packages/runner/src/commands/test/compare-screenshot.js

@@ -37,7 +37,8 @@ async function compareScreenshot(
 
   const isEqual = await getImageDiffer(
     options.diffingEngine,
-    options[options.diffingEngine]
+    options[options.diffingEngine],
+    options.includeReferenceOnDiff
   )(referencePath, outputPath, diffPath, tolerance);
 
   if (!isEqual) {

packages/runner/src/commands/test/get-image-differ.js

@@ -2,11 +2,11 @@ const { createGraphicsMagickDiffer } = require('@loki/diff-graphics-magick');
 const { createLooksSameDiffer } = require('@loki/diff-looks-same');
 const { createPixelmatchDiffer } = require('@loki/diff-pixelmatch');
 
-function getImageDiffer(engine, config) {
+function getImageDiffer(engine, config, includeReferenceOnDiff) {
   switch (engine) {
     case undefined:
     case 'pixelmatch': {
-      return createPixelmatchDiffer(config);
+      return createPixelmatchDiffer(config, includeReferenceOnDiff);
     }
     case 'looks-same': {
       return createLooksSameDiffer(config);

packages/runner/src/commands/test/parse-options.js

@@ -44,6 +44,7 @@ function parseOptions(args, config) {
     skipStoriesPattern: $('skipStories'),
     storiesFilter: $('storiesFilter'),
     diffingEngine: $('diffingEngine') || 'pixelmatch',
+    includeReferenceOnDiff: $('includeReferenceOnDiff'),
     fetchFailIgnore: $('fetchFailIgnore'),
     'looks-same': $('looks-same'),
     gm: $('gm'),