@jsenv/snapshot 2.18.11 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/snapshot",
-  "version": "2.18.11",
+  "version": "2.19.0",
   "type": "module",
   "description": "Snapshot testing",
   "repository": {
@@ -28,7 +28,7 @@
   ],
   "dependencies": {
     "@jsenv/assert": "4.5.7",
-    "@jsenv/ast": "6.8.4",
+    "@jsenv/ast": "6.8.5",
     "@jsenv/exception": "1.2.2",
     "@jsenv/filesystem": "4.15.17",
     "@jsenv/humanize": "1.7.8",

package/src/compare_png_files.js

@@ -1,49 +1,102 @@
-// https://github.com/image-size/image-size/blob/main/lib/types/png.ts
+/*
+ * Compare two PNG buffers visually: a screenshot re-generated on a different
+ * machine (or just a different run) is never byte-identical because of
+ * antialiasing, subpixel rounding and compression, so a byte comparison is
+ * useless as a regression signal.
+ *
+ * Two images that cannot be compared (different dimensions, unreadable data)
+ * are reported as different, never as an error: "the image changed" is a
+ * normal outcome, not a failure of the comparison itself.
+ */
 
 import pixelmatch from "pixelmatch";
 import { PNG } from "pngjs";
 
-export const comparePngFiles = (actualData, expectData) => {
-  const { width, height } = getPngDimensions(actualData);
-  const actualPng = PNG.sync.read(actualData);
-  const expectPng = PNG.sync.read(expectData);
-  const numberOfPixels = width * height;
-  const numberOfPixelsConsideredAsDiff = pixelmatch(
+/**
+ * @param {Buffer} actualData
+ * @param {Buffer} expectData
+ * @param {Object} [options]
+ * @param {number} [options.threshold] pixelmatch per pixel color sensitivity, from 0 (strict) to 1 (permissive)
+ * @param {number} [options.maxDiffRatio] ratio of differing pixels still considered as "same", from 0 to 1
+ * @param {boolean} [options.includeAA] count antialiased pixels as differences
+ * @param {boolean} [options.createDiff] generate a PNG highlighting the differing pixels
+ * @returns {{ same: boolean, reason: "size"|"pixels"|"unreadable"|undefined, width: number, height: number, diffPixelCount: number, diffRatio: number, diffFileContent: Buffer|undefined }}
+ */
+export const comparePngFilesDetailed = (
+  actualData,
+  expectData,
+  { threshold = 0.1, maxDiffRatio = 0.01, includeAA = false, createDiff } = {},
+) => {
+  let actualPng;
+  let expectPng;
+  try {
+    actualPng = PNG.sync.read(actualData);
+    expectPng = PNG.sync.read(expectData);
+  } catch {
+    return createResult({ same: false, reason: "unreadable" });
+  }
+  const { width, height } = actualPng;
+  if (width !== expectPng.width || height !== expectPng.height) {
+    return createResult({
+      same: false,
+      reason: "size",
+      width,
+      height,
+    });
+  }
+  const pixelCount = width * height;
+  // pngjs decodes some PNG (16 bits, exotic palettes) into something else than
+  // the RGBA buffer pixelmatch expects; there is nothing to compare then
+  if (
+    actualPng.data.length !== pixelCount * 4 ||
+    expectPng.data.length !== pixelCount * 4
+  ) {
+    return createResult({
+      same: false,
+      reason: "unreadable",
+      width,
+      height,
+    });
+  }
+  const diffPng = createDiff ? new PNG({ width, height }) : null;
+  const diffPixelCount = pixelmatch(
     actualPng.data,
     expectPng.data,
-    null,
+    diffPng ? diffPng.data : null,
     width,
     height,
-    {
-      threshold: 0.1,
-    },
+    { threshold, includeAA },
   );
-  const diffRatio = numberOfPixelsConsideredAsDiff / numberOfPixels;
-  const diffPercentage = diffRatio * 100;
-  return diffPercentage <= 1;
-};
-
-const getPngDimensions = (buffer) => {
-  if (toUTF8String(buffer, 12, 16) === pngFriedChunkName) {
-    return {
-      height: readUInt32BE(buffer, 36),
-      width: readUInt32BE(buffer, 32),
-    };
-  }
-  return {
-    height: readUInt32BE(buffer, 20),
-    width: readUInt32BE(buffer, 16),
-  };
+  const diffRatio = diffPixelCount / pixelCount;
+  const same = diffRatio <= maxDiffRatio;
+  return createResult({
+    same,
+    reason: same ? undefined : "pixels",
+    width,
+    height,
+    diffPixelCount,
+    diffRatio,
+    diffFileContent: diffPng ? PNG.sync.write(diffPng) : undefined,
+  });
 };
 
-const pngFriedChunkName = "CgBI";
-
-const decoder = new TextDecoder();
-const toUTF8String = (input, start = 0, end = input.length) =>
-  decoder.decode(input.slice(start, end));
+export const comparePngFiles = (actualData, expectData, options) =>
+  comparePngFilesDetailed(actualData, expectData, options).same;
 
-const readUInt32BE = (input, offset = 0) =>
-  input[offset] * 2 ** 24 +
-  input[offset + 1] * 2 ** 16 +
-  input[offset + 2] * 2 ** 8 +
-  input[offset + 3];
+const createResult = ({
+  same,
+  reason,
+  width = 0,
+  height = 0,
+  diffPixelCount = 0,
+  diffRatio = same ? 0 : 1,
+  diffFileContent,
+}) => ({
+  same,
+  reason,
+  width,
+  height,
+  diffPixelCount,
+  diffRatio,
+  diffFileContent,
+});

package/src/filesystem_snapshot.js

@@ -18,7 +18,7 @@ import {
 import { CONTENT_TYPE } from "@jsenv/utils/src/content_type/content_type.js";
 import { readdirSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { comparePngFiles } from "./compare_png_files.js";
+import { comparePngFilesDetailed } from "./compare_png_files.js";
 import {
   ExtraFileAssertionError,
   FileContentAssertionError,
@@ -27,12 +27,14 @@ import {
 } from "./errors.js";
 import { replaceFluctuatingValues } from "./replace_fluctuating_values.js";
 
-export const takeFileSnapshot = (fileUrl) => {
+export const takeFileSnapshot = (fileUrl, { png } = {}) => {
   fileUrl = assertAndNormalizeFileUrl(fileUrl);
-  const fileSnapshot = createFileSnapshot(fileUrl);
+  const fileSnapshot = createFileSnapshot(fileUrl, { png });
   removeFileSync(fileUrl, { allowUseless: true });
   const compare = (throwWhenDiff = process.env.CI) => {
-    fileSnapshot.compare(createFileSnapshot(fileUrl), { throwWhenDiff });
+    fileSnapshot.compare(createFileSnapshot(fileUrl, { png }), {
+      throwWhenDiff,
+    });
   };
   return {
     compare,
@@ -61,7 +63,7 @@ export const takeFileSnapshot = (fileUrl) => {
     },
   };
 };
-const createFileSnapshot = (fileUrl) => {
+const createFileSnapshot = (fileUrl, { png } = {}) => {
   const fileSnapshot = {
     type: "file",
     url: fileUrl,
@@ -93,12 +95,19 @@ ${fileUrl}`);
         if (nextFileContent.equals(fileContent)) {
           return;
         }
+        let reason = "content has changed";
         if (fileSnapshot.contentType === "image/png") {
-          if (comparePngFiles(fileContent, nextFileContent)) {
+          const pngComparison = comparePngFilesDetailed(
+            fileContent,
+            nextFileContent,
+            png,
+          );
+          if (pngComparison.same) {
             // restore old version to prevent git diff
             writeFileSync(fileUrl, fileContent);
             return;
           }
+          reason = describePngDiff(pngComparison);
         }
         if (!throwWhenDiff) {
           return;
@@ -106,7 +115,7 @@ ${fileUrl}`);
         const fileContentAssertionError =
           new FileContentAssertionError(`${failureMessage}
 --- reason ---
-content has changed
+${reason}
 --- file ---
 ${fileUrl}`);
         throw fileContentAssertionError;
@@ -167,6 +176,7 @@ export const takeDirectorySnapshot = (
     "**/*": true,
     "**/.*/": false,
   },
+  { png } = {},
 ) => {
   directoryUrl = assertAndNormalizeDirectoryUrl(directoryUrl);
   directoryUrl = new URL(directoryUrl);
@@ -205,6 +215,7 @@ export const takeDirectorySnapshot = (
     shouldVisitDirectory,
     shouldIncludeFile,
     shouldCompareFileContent,
+    png,
     clean: true,
   });
   return {
@@ -214,6 +225,7 @@ export const takeDirectorySnapshot = (
         shouldVisitDirectory,
         shouldIncludeFile,
         shouldCompareFileContent,
+        png,
       });
       directorySnapshot.compare(nextDirectorySnapshot, { throwWhenDiff });
     },
@@ -241,7 +253,13 @@ export const takeDirectorySnapshot = (
 };
 const createDirectorySnapshot = (
   directoryUrl,
-  { shouldVisitDirectory, shouldIncludeFile, shouldCompareFileContent, clean },
+  {
+    shouldVisitDirectory,
+    shouldIncludeFile,
+    shouldCompareFileContent,
+    png,
+    clean,
+  },
 ) => {
   const directorySnapshot = {
     type: "directory",
@@ -393,6 +411,7 @@ ${extraUrls.join("\n")}`);
           shouldVisitDirectory,
           shouldIncludeFile,
           shouldCompareFileContent,
+          png,
           clean,
         });
         contentSnapshotNaturalOrder[relativeUrl] = subdirSnapshot;
@@ -404,8 +423,10 @@ ${extraUrls.join("\n")}`);
       if (!shouldIncludeFile(directoryItemUrl.href)) {
         continue;
       }
-      contentSnapshotNaturalOrder[relativeUrl] =
-        createFileSnapshot(directoryItemUrl);
+      contentSnapshotNaturalOrder[relativeUrl] = createFileSnapshot(
+        directoryItemUrl,
+        { png },
+      );
       if (clean) {
         removeFileSync(directoryItemUrl, { allowUseless: true });
       }
@@ -424,3 +445,14 @@ ${extraUrls.join("\n")}`);
   });
   return directorySnapshot;
 };
+
+const describePngDiff = ({ reason, diffPixelCount, diffRatio }) => {
+  if (reason === "size") {
+    return "image dimensions have changed";
+  }
+  if (reason === "unreadable") {
+    return "image cannot be compared";
+  }
+  const diffPercentage = (diffRatio * 100).toFixed(3);
+  return `${diffPixelCount} pixels have changed (${diffPercentage}%)`;
+};

package/src/main.js

@@ -1,3 +1,7 @@
+export {
+  comparePngFiles,
+  comparePngFilesDetailed,
+} from "./compare_png_files.js";
 export {
   takeDirectorySnapshot,
   takeFileSnapshot,