@jsenv/snapshot 1.3.8 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/snapshot",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "Snapshot testing",
   "license": "MIT",
   "author": {
@@ -35,10 +35,11 @@
     "test": "node --conditions=development ./scripts/test.mjs"
   },
   "dependencies": {
-    "@jsenv/filesystem": "4.6.9",
+    "@jsenv/assert": "4.0.10",
+    "@jsenv/filesystem": "4.7.1",
     "@jsenv/urls": "2.2.7",
     "@jsenv/utils": "2.1.1",
-    "@jsenv/assert": "4.0.8",
+    "pixelmatch": "6.0.0",
     "prettier": "3.3.2"
   },
   "devDependencies": {

package/src/compare_png_files.js

@@ -0,0 +1,49 @@
+// https://github.com/image-size/image-size/blob/main/lib/types/png.ts
+
+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(
+    actualPng.data,
+    expectPng.data,
+    null,
+    width,
+    height,
+    {
+      threshold: 0.1,
+    },
+  );
+  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 pngFriedChunkName = "CgBI";
+
+const decoder = new TextDecoder();
+const toUTF8String = (input, start = 0, end = input.length) =>
+  decoder.decode(input.slice(start, end));
+
+const readUInt32BE = (input, offset = 0) =>
+  input[offset] * 2 ** 24 +
+  input[offset + 1] * 2 ** 16 +
+  input[offset + 2] * 2 ** 8 +
+  input[offset + 3];

package/src/errors.js

@@ -0,0 +1,6 @@
+import { assert } from "@jsenv/assert";
+
+export class FileContentNotFoundAssertionError extends assert.AssertionError {}
+export class FileMissingAssertionError extends assert.AssertionError {}
+export class ExtraFileAssertionError extends assert.AssertionError {}
+export class FileContentAssertionError extends assert.AssertionError {}

package/src/file_snapshots.js

@@ -1,4 +1,5 @@
 import { readdirSync, statSync, readFileSync } from "node:fs";
+import { URL_META } from "@jsenv/url-meta";
 import {
   assertAndNormalizeDirectoryUrl,
   assertAndNormalizeFileUrl,
@@ -7,31 +8,39 @@ import {
   removeFileSync,
   writeFileSync,
   removeDirectorySync,
-  writeFileStructureSync,
 } from "@jsenv/filesystem";
-import { urlToFilename, urlToRelativeUrl } from "@jsenv/urls";
 import { CONTENT_TYPE } from "@jsenv/utils/src/content_type/content_type.js";
+import { urlToRelativeUrl, urlToFilename } from "@jsenv/urls";
 
 import { assert } from "@jsenv/assert";
+import {
+  FileContentNotFoundAssertionError,
+  FileMissingAssertionError,
+  ExtraFileAssertionError,
+  FileContentAssertionError,
+} from "./errors.js";
+import { comparePngFiles } from "./compare_png_files.js";
 
 export const takeFileSnapshot = (fileUrl) => {
   fileUrl = assertAndNormalizeFileUrl(fileUrl);
-  const expectedFileSnapshot = createFileSnapshot(fileUrl);
+  const fileSnapshot = createFileSnapshot(fileUrl);
   removeFileSync(fileUrl, { allowUseless: true });
-
   return {
-    compare: () => {
-      compareFileSnapshots(createFileSnapshot(fileUrl), expectedFileSnapshot);
+    compare: (doIt = process.env.CI) => {
+      if (!doIt) {
+        return;
+      }
+      fileSnapshot.compare(createFileSnapshot(fileUrl));
     },
     writeContent: (content) => {
       writeFileSync(fileUrl, content);
     },
     restore: () => {
-      if (expectedFileSnapshot.empty) {
+      if (fileSnapshot.empty) {
         removeFileSync(fileUrl, { allowUseless: true });
         return;
       }
-      writeFileSync(fileUrl, expectedFileSnapshot.content);
+      writeFileSync(fileUrl, fileSnapshot.content);
     },
   };
 };
@@ -40,7 +49,54 @@ const createFileSnapshot = (fileUrl) => {
     type: "file",
     url: fileUrl,
     stat: null,
+    contentType: CONTENT_TYPE.fromUrlExtension(fileUrl),
     content: "",
+    compare: (nextFileSnapshot) => {
+      const filename = urlToFilename(fileUrl);
+      const failureMessage = `snapshot comparison failed for "${filename}"`;
+
+      if (!nextFileSnapshot.stat) {
+        const fileNotFoundAssertionError =
+          new FileContentNotFoundAssertionError(`${failureMessage}
+--- reason ---
+file not found
+--- file ---
+${fileUrl}`);
+        throw fileNotFoundAssertionError;
+      }
+      if (!fileSnapshot.stat) {
+        return;
+      }
+      const fileContent = fileSnapshot.content;
+      const nextFileContent = nextFileSnapshot.content;
+      if (Buffer.isBuffer(nextFileContent)) {
+        if (nextFileContent.equals(fileContent)) {
+          return;
+        }
+        if (nextFileContent.contentType === "image/png") {
+          if (comparePngFiles(fileContent, nextFileContent)) {
+            return;
+          }
+        }
+        const fileContentAssertionError =
+          new FileContentAssertionError(`${failureMessage}
+--- reason ---
+content has changed
+--- file ---
+${fileUrl}`);
+        throw fileContentAssertionError;
+      }
+      if (nextFileContent === fileContent) {
+        return;
+      }
+      assert({
+        message: failureMessage,
+        actual: nextFileContent,
+        expect: fileContent,
+        details: fileUrl,
+        forceMultilineDiff: true,
+      });
+    },
   };
 
   try {
@@ -55,9 +111,7 @@ const createFileSnapshot = (fileUrl) => {
     throw new Error(`file expect at ${fileUrl}`);
   }
 
-  const isTextual = CONTENT_TYPE.isTextual(
-    CONTENT_TYPE.fromUrlExtension(fileUrl),
-  );
+  const isTextual = CONTENT_TYPE.isTextual(fileSnapshot.contentType);
   if (isTextual) {
     const contentAsString = readFileSync(new URL(fileUrl), "utf8");
     if (process.platform === "win32") {
@@ -76,63 +130,86 @@ const createFileSnapshot = (fileUrl) => {
   }
   return fileSnapshot;
 };
-const compareFileSnapshots = (actualFileSnapshot, expectedFileSnapshot) => {
-  const fileUrl = actualFileSnapshot.url;
-  const filename = urlToFilename(fileUrl);
-  const failureMessage = `snapshot comparison failed for "${filename}"`;
 
-  if (!actualFileSnapshot.stat) {
-    const fileNotFoundAssertionError =
-      assert.createAssertionError(`${failureMessage}
---- reason ---
-file not found
---- file ---
-${fileUrl}`);
-    fileNotFoundAssertionError.name = "FileNotFoundAssertionError";
-    throw fileNotFoundAssertionError;
-  }
-  if (!expectedFileSnapshot.stat) {
-    return;
-  }
-  const actualFileContent = actualFileSnapshot.content;
-  const expectedFileContent = expectedFileSnapshot.content;
-  if (Buffer.isBuffer(actualFileContent)) {
-    if (actualFileContent.equals(expectedFileContent)) {
-      return;
-    }
-    const fileContentAssertionError =
-      assert.createAssertionError(`${failureMessage}
---- reason ---
-content has changed
---- file ---
-${fileUrl}`);
-    fileContentAssertionError.name = "FileContentAssertionError";
-    throw fileContentAssertionError;
-  }
-  if (actualFileContent === expectedFileContent) {
-    return;
-  }
-  assert({
-    message: failureMessage,
-    details: fileUrl,
-    actual: actualFileContent,
-    expect: expectedFileContent,
-    forceMultilineDiff: true,
-  });
-};
-
-export const takeDirectorySnapshot = (directoryUrl) => {
+export const takeDirectorySnapshot = (
+  directoryUrl,
+  pattern = { "**/*": true },
+) => {
   directoryUrl = assertAndNormalizeDirectoryUrl(directoryUrl);
   directoryUrl = new URL(directoryUrl);
-
-  const expectedDirectorySnapshot = createDirectorySnapshot(directoryUrl);
-  ensureEmptyDirectorySync(directoryUrl);
+  const associations = URL_META.resolveAssociations(
+    {
+      included: pattern,
+    },
+    directoryUrl,
+  );
+  const predicate = ({ included }) => included;
+  const shouldVisitDirectory = (url) =>
+    URL_META.urlChildMayMatch({
+      url,
+      associations,
+      predicate,
+    });
+  const shouldIncludeFile = (url) =>
+    predicate(
+      URL_META.applyAssociations({
+        url,
+        associations,
+      }),
+    );
+  const directorySnapshot = createDirectorySnapshot(directoryUrl, {
+    shouldVisitDirectory,
+    shouldIncludeFile,
+    clean: true,
+  });
   return {
-    compare: () => {
+    __snapshot: directorySnapshot,
+    compare: (doIt = process.env.CI) => {
+      if (!doIt) {
+        return;
+      }
+      const nextDirectorySnapshot = createDirectorySnapshot(directoryUrl, {
+        shouldVisitDirectory,
+        shouldIncludeFile,
+      });
+      directorySnapshot.compare(nextDirectorySnapshot);
+    },
+    addFile: (relativeUrl, content) => {
+      writeFileSync(new URL(relativeUrl, directoryUrl), content);
+    },
+    restore: () => {
+      if (directorySnapshot.notFound) {
+        removeDirectorySync(directoryUrl, {
+          recursive: true,
+          allowUseless: true,
+        });
+        return;
+      }
+      if (directorySnapshot.empty) {
+        ensureEmptyDirectorySync(directoryUrl);
+        return;
+      }
+      for (const relativeUrl of directorySnapshot.contentSnapshot) {
+        const snapshot = directorySnapshot.contentSnapshot[relativeUrl];
+        snapshot.restore();
+      }
+    },
+  };
+};
+const createDirectorySnapshot = (
+  directoryUrl,
+  { shouldVisitDirectory, shouldIncludeFile, clean },
+) => {
+  const directorySnapshot = {
+    type: "directory",
+    url: directoryUrl.href,
+    stat: null,
+    empty: false,
+    contentSnapshot: {},
+    compare: (nextDirectorySnapshot) => {
       const dirname = `${urlToFilename(directoryUrl)}/`;
       const failureMessage = `snapshot comparison failed for "${dirname}"`;
-      const actualDirectorySnapshot = createDirectorySnapshot(directoryUrl);
-      if (!expectedDirectorySnapshot.stat || expectedDirectorySnapshot.empty) {
+      if (!directorySnapshot.stat || directorySnapshot.empty) {
         // the snapshot taken for directory/file/whatever is empty:
         // - first time code executes:
         //   it defines snapshot that will be used for comparison by future runs
@@ -142,17 +219,15 @@ export const takeDirectorySnapshot = (directoryUrl) => {
         //   to review them using git diff)
         return;
       }
-
-      const actualFileSnapshots = actualDirectorySnapshot.fileSnapshots;
-      const expectedFileSnapshots = expectedDirectorySnapshot.fileSnapshots;
-      const actualRelativeUrls = Object.keys(actualFileSnapshots);
-      const expectedRelativeUrls = Object.keys(expectedFileSnapshots);
-
-      // missing_files
+      const directoryContentSnapshot = directorySnapshot.contentSnapshot;
+      const relativeUrls = Object.keys(directoryContentSnapshot);
+      const nextDirectoryContentSnapshot =
+        nextDirectorySnapshot.contentSnapshot;
+      const nextRelativeUrls = Object.keys(nextDirectoryContentSnapshot);
+      // missing content
       {
-        const missingRelativeUrls = expectedRelativeUrls.filter(
-          (expectedRelativeUrl) =>
-            !actualRelativeUrls.includes(expectedRelativeUrl),
+        const missingRelativeUrls = relativeUrls.filter(
+          (relativeUrl) => !nextRelativeUrls.includes(relativeUrl),
         );
         const missingFileCount = missingRelativeUrls.length;
         if (missingFileCount > 0) {
@@ -161,30 +236,26 @@ export const takeDirectorySnapshot = (directoryUrl) => {
           );
           if (missingFileCount === 1) {
             const fileMissingAssertionError =
-              assert.createAssertionError(`${failureMessage}
+              new FileMissingAssertionError(`${failureMessage}
 --- reason ---
-"${missingRelativeUrls[0]}" is missing
---- file missing ---
+"${missingRelativeUrls[0]}" directory entry is missing
+--- missing entry ---
 ${missingUrls[0]}`);
-            fileMissingAssertionError.name = "FileMissingAssertionError";
             throw fileMissingAssertionError;
           }
           const fileMissingAssertionError =
-            assert.createAssertionError(`${failureMessage}
+            new FileMissingAssertionError(`${failureMessage}
 --- reason ---
-${missingFileCount} files are missing
---- files missing ---
+${missingFileCount} directory entries are missing
+--- missing entries ---
 ${missingUrls.join("\n")}`);
-          fileMissingAssertionError.name = "FileMissingAssertionError";
           throw fileMissingAssertionError;
         }
       }
-
-      // unexpected files
+      // unexpected content
       {
-        const extraRelativeUrls = actualRelativeUrls.filter(
-          (actualRelativeUrl) =>
-            !expectedRelativeUrls.includes(actualRelativeUrl),
+        const extraRelativeUrls = nextRelativeUrls.filter(
+          (nextRelativeUrl) => !relativeUrls.includes(nextRelativeUrl),
         );
         const extraFileCount = extraRelativeUrls.length;
         if (extraFileCount > 0) {
@@ -193,78 +264,34 @@ ${missingUrls.join("\n")}`);
           );
           if (extraFileCount === 1) {
             const extraFileAssertionError =
-              assert.createAssertionError(`${failureMessage}
+              new ExtraFileAssertionError(`${failureMessage}
 --- reason ---
-"${extraRelativeUrls[0]}" is unexpected
---- file unexpected ---
+"${extraRelativeUrls[0]}" directory entry is unexpected
+--- unexpected entry ---
 ${extraUrls[0]}`);
-            extraFileAssertionError.name = "ExtraFileAssertionError";
             throw extraFileAssertionError;
           }
           const extraFileAssertionError =
-            assert.createAssertionError(`${failureMessage}
+            new ExtraFileAssertionError(`${failureMessage}
 --- reason ---
-${extraFileCount} files are unexpected
---- files unexpected ---
+${extraFileCount} directory entries are unexpected
+--- unexpected entries ---
 ${extraUrls.join("\n")}`);
-          extraFileAssertionError.name = "ExtraFileAssertionError";
           throw extraFileAssertionError;
         }
       }
-
-      // file contents
+      // content
       {
-        for (const relativeUrl of actualRelativeUrls) {
-          const actualFileSnapshot = actualFileSnapshots[relativeUrl];
-          const expectedFileSnapshot = expectedFileSnapshots[relativeUrl];
-          compareFileSnapshots(actualFileSnapshot, expectedFileSnapshot);
+        for (const relativeUrl of nextRelativeUrls) {
+          const snapshot = directoryContentSnapshot[relativeUrl];
+          const nextSnapshot = nextDirectoryContentSnapshot[relativeUrl];
+          snapshot.compare(nextSnapshot);
         }
       }
     },
-    addFile: (relativeUrl, content) => {
-      writeFileSync(new URL(relativeUrl, directoryUrl), content);
-    },
-    restore: () => {
-      if (expectedDirectorySnapshot.notFound) {
-        removeDirectorySync(directoryUrl, {
-          recursive: true,
-          allowUseless: true,
-        });
-        return;
-      }
-      if (expectedDirectorySnapshot.empty) {
-        ensureEmptyDirectorySync(directoryUrl);
-        return;
-      }
-
-      const fileStructure = {};
-      Object.keys(expectedDirectorySnapshot.fileSnapshots).forEach(
-        (relativeUrl) => {
-          const fileSnapshot =
-            expectedDirectorySnapshot.fileSnapshots[relativeUrl];
-          if (!fileSnapshot.empty) {
-            fileStructure[relativeUrl] = fileSnapshot.content;
-          }
-        },
-      );
-      writeFileStructureSync(
-        directoryUrl,
-        expectedDirectorySnapshot.fileStructure,
-      );
-    },
-  };
-};
-const createDirectorySnapshot = (directoryUrl) => {
-  const directorySnapshot = {
-    type: "directory",
-    url: directoryUrl.href,
-    stat: null,
-    empty: false,
-    fileSnapshots: {},
   };
-
   try {
-    directorySnapshot.stat = statSync(directoryUrl);
+    directorySnapshot.stat = statSync(new URL(directoryUrl));
   } catch (e) {
     if (e.code === "ENOENT") {
       return directorySnapshot;
@@ -272,48 +299,67 @@ const createDirectorySnapshot = (directoryUrl) => {
     if (e.code === "ENOTDIR") {
       // trailing slash is forced on directoryUrl
       // as a result Node.js throw ENOTDIR when doing "stat" operation
-      throw new Error(`directory expect at ${directoryUrl}`);
+      throw new Error(`directory expected at ${directoryUrl}`);
     }
     throw e;
   }
   if (!directorySnapshot.stat.isDirectory()) {
-    throw new Error(`directory expect at ${directoryUrl}`);
+    throw new Error(`directory expected at ${directoryUrl}`);
   }
-
   const entryNames = readdirSync(directoryUrl);
   if (entryNames.length === 0) {
     directorySnapshot.empty = true;
     return directorySnapshot;
   }
-
-  const fileSnapshotsNaturalOrder = {};
-  const visitDirectory = (url) => {
-    try {
-      const directoryContent = readdirSync(url);
-      for (const filename of directoryContent) {
-        const contentUrl = new URL(filename, url);
-        const stat = statSync(contentUrl);
-        if (stat.isDirectory()) {
-          visitDirectory(new URL(`${contentUrl}/`));
-          return;
+  const contentSnapshotNaturalOrder = {};
+  try {
+    const directoryItemArray = readdirSync(directoryUrl);
+    for (const directoryItem of directoryItemArray) {
+      const directoryItemUrl = new URL(directoryItem, directoryUrl);
+      let directoryItemStat;
+      try {
+        directoryItemStat = statSync(directoryItemUrl);
+      } catch (e) {
+        if (e.code === "ENOENT") {
+          continue;
         }
-        const relativeUrl = urlToRelativeUrl(contentUrl, directoryUrl);
-        fileSnapshotsNaturalOrder[relativeUrl] = createFileSnapshot(contentUrl);
+        throw e;
       }
-    } catch (e) {
-      if (e && e.code === "ENOENT") {
-        return;
+      const relativeUrl = urlToRelativeUrl(directoryItemUrl, directoryUrl);
+      if (directoryItemStat.isDirectory()) {
+        if (!shouldVisitDirectory(directoryUrl)) {
+          continue;
+        }
+        contentSnapshotNaturalOrder[relativeUrl] = createDirectorySnapshot(
+          new URL(`${directoryItemUrl}/`),
+          {
+            shouldVisitDirectory,
+            shouldIncludeFile,
+            clean,
+          },
+        );
+        continue;
+      }
+      if (!shouldIncludeFile(directoryItemUrl)) {
+        continue;
       }
+      contentSnapshotNaturalOrder[relativeUrl] =
+        createFileSnapshot(directoryItemUrl);
+      if (clean) {
+        removeFileSync(directoryItemUrl, { allowUseless: true });
+      }
+    }
+  } catch (e) {
+    if (e && e.code === "ENOENT") {
+    } else {
       throw e;
     }
-  };
-  visitDirectory(directoryUrl);
-
-  const relativeUrls = Object.keys(fileSnapshotsNaturalOrder);
+  }
+  const relativeUrls = Object.keys(contentSnapshotNaturalOrder);
   relativeUrls.sort(comparePathnames);
   relativeUrls.forEach((relativeUrl) => {
-    directorySnapshot.fileSnapshots[relativeUrl] =
-      fileSnapshotsNaturalOrder[relativeUrl];
+    directorySnapshot.contentSnapshot[relativeUrl] =
+      contentSnapshotNaturalOrder[relativeUrl];
   });
   return directorySnapshot;
 };