@jsenv/snapshot 2.6.6 → 2.6.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/snapshot",
-  "version": "2.6.6",
+  "version": "2.6.7",
   "description": "Snapshot testing",
   "license": "MIT",
   "author": {
@@ -34,12 +34,14 @@
     "test": "node --conditions=development ./scripts/test.mjs"
   },
   "dependencies": {
-    "@jsenv/assert": "4.1.12",
-    "@jsenv/ast": "6.2.10",
+    "@jsenv/assert": "4.1.13",
+    "@jsenv/ast": "6.2.11",
     "@jsenv/exception": "1.0.1",
-    "@jsenv/filesystem": "4.9.5",
-    "@jsenv/urls": "2.4.1",
+    "@jsenv/filesystem": "4.9.6",
+    "@jsenv/terminal-recorder": "1.4.2",
+    "@jsenv/urls": "2.5.0",
     "@jsenv/utils": "2.1.2",
+    "ansi-regex": "6.0.1",
     "pixelmatch": "6.0.0",
     "prettier": "3.3.3",
     "strip-ansi": "7.1.0"

package/src/filesystem_well_known_values.js

@@ -1,6 +1,7 @@
 import {
   ensurePathnameTrailingSlash,
   removePathnameTrailingSlash,
+  yieldAncestorUrls,
 } from "@jsenv/urls";
 import { escapeRegexpSpecialChars } from "@jsenv/utils/src/string/escape_regexp_special_chars.js";
 import { readFileSync } from "node:fs";
@@ -114,6 +115,16 @@ export const createReplaceFilesystemWellKnownValues = ({
       wellKownUrlArray.push(wellKnownUrl);
       wellKnownPathArray.push(wellKnownPath);
     }
+    return () => {
+      const urlIndex = wellKownUrlArray.indexOf(wellKnownUrl);
+      if (urlIndex > -1) {
+        wellKownUrlArray.splice(urlIndex, 1);
+      }
+      const pathIndex = wellKnownPathArray.indexOf(wellKnownPath);
+      if (pathIndex !== -1) {
+        wellKnownPathArray.splice(pathIndex, 1);
+      }
+    };
   };
   if (rootDirectoryUrl) {
     addWellKnownFileUrl(rootDirectoryUrl, WELL_KNOWN_ROOT);
@@ -136,11 +147,13 @@ export const createReplaceFilesystemWellKnownValues = ({
     const ancestorPackages = [];
     const cwd = cwdPath || process.cwd();
     const cwdUrl = ensurePathnameTrailingSlash(pathToFileURL(cwd));
-    let currentUrl = cwdUrl;
-    while (currentUrl.href !== ancestorPackagesRootDirectoryUrl) {
-      const packageFileUrl = new URL("package.json", currentUrl);
-      const packageDirectoryUrl = currentUrl;
-      currentUrl = new URL(getParentUrl(currentUrl));
+    for (const ancestorUrl of yieldAncestorUrls(
+      cwdUrl,
+      ancestorPackagesRootDirectoryUrl,
+      { yieldSelf: true },
+    )) {
+      const packageFileUrl = new URL("package.json", ancestorUrl);
+      const packageDirectoryUrl = ancestorUrl;
       let packageFileContent;
       try {
         packageFileContent = readFileSync(packageFileUrl);
@@ -226,24 +239,3 @@ export const createReplaceFilesystemWellKnownValues = ({
   replaceFilesystemWellKnownValues.addWellKnownFileUrl = addWellKnownFileUrl;
   return replaceFilesystemWellKnownValues;
 };
-
-const getParentUrl = (url) => {
-  url = String(url);
-  // With node.js new URL('../', 'file:///C:/').href
-  // returns "file:///C:/" instead of "file:///"
-  const resource = url.slice("file://".length);
-  const slashLastIndex = resource.lastIndexOf("/");
-  if (slashLastIndex === -1) {
-    return url;
-  }
-  const lastCharIndex = resource.length - 1;
-  if (slashLastIndex === lastCharIndex) {
-    const slashBeforeLastIndex = resource.lastIndexOf("/", slashLastIndex - 1);
-    if (slashBeforeLastIndex === -1) {
-      return url;
-    }
-    return `file://${resource.slice(0, slashBeforeLastIndex + 1)}`;
-  }
-
-  return `file://${resource.slice(0, slashLastIndex + 1)}`;
-};

package/src/get_caller_location.js

@@ -0,0 +1,22 @@
+import { fileSystemPathToUrl, isFileSystemPath } from "@jsenv/urls";
+
+export const getCallerLocation = (callIndex = 1) => {
+  const { prepareStackTrace } = Error;
+  Error.prepareStackTrace = (error, stack) => {
+    Error.prepareStackTrace = prepareStackTrace;
+    return stack;
+  };
+  const { stack } = new Error();
+  Error.prepareStackTrace = prepareStackTrace;
+  const callerCallsite = stack[callIndex];
+  const fileName = callerCallsite.getFileName();
+  const testCallSite = {
+    url:
+      fileName && isFileSystemPath(fileName)
+        ? fileSystemPathToUrl(fileName)
+        : fileName,
+    line: callerCallsite.getLineNumber(),
+    column: callerCallsite.getColumnNumber(),
+  };
+  return testCallSite;
+};

package/src/main.js

@@ -3,5 +3,8 @@ export {
   takeFileSnapshot,
 } from "./filesystem_snapshot.js";
 export { createReplaceFilesystemWellKnownValues } from "./filesystem_well_known_values.js";
-export { snapshotFunctionSideEffects } from "./function_side_effects/function_side_effects_snapshot.js";
+export { getCallerLocation } from "./get_caller_location.js";
 export { replaceFluctuatingValues } from "./replace_fluctuating_values.js";
+export { renderLogsGif } from "./side_effects/render_logs_gif.js";
+export { snapshotSideEffects } from "./side_effects/snapshot_side_effects.js";
+export { snapshotTests } from "./side_effects/snapshot_tests.js";

package/src/replace_fluctuating_values.js

@@ -61,7 +61,7 @@ export const replaceFluctuatingValues = (
     value = replaceDurations(value);
     return value;
   };
-  if (stringType === "html") {
+  if (stringType === "html" || stringType === "svg") {
     // do parse html
     const htmlAst =
       stringType === "svg"

package/src/side_effects/capture_side_effects.js

@@ -0,0 +1,6 @@
+import { createCaptureSideEffects } from "./create_capture_side_effects.js";
+
+export const captureSideEffects = (fn, options) => {
+  const capture = createCaptureSideEffects(options);
+  return capture(fn);
+};

package/src/side_effects/create_capture_side_effects.js

@@ -0,0 +1,305 @@
+import { parseFunction } from "@jsenv/assert/src/utils/function_parser.js";
+import { createReplaceFilesystemWellKnownValues } from "../filesystem_well_known_values.js";
+import { filesystemSideEffects } from "./filesystem/filesystem_side_effects.js";
+import { logSideEffects } from "./log/log_side_effects.js";
+
+export const createCaptureSideEffects = ({
+  logEffects = true,
+  filesystemEffects = true,
+  rootDirectoryUrl,
+  replaceFilesystemWellKnownValues = createReplaceFilesystemWellKnownValues({
+    rootDirectoryUrl,
+  }),
+} = {}) => {
+  const detectors = [];
+  if (logEffects) {
+    detectors.push(logSideEffects(logEffects === true ? {} : logEffects));
+  }
+  let filesystemSideEffectsDetector;
+  if (filesystemEffects) {
+    filesystemSideEffectsDetector = filesystemSideEffects(
+      filesystemEffects === true ? {} : filesystemEffects,
+      {
+        replaceFilesystemWellKnownValues,
+      },
+    );
+    detectors.push(filesystemSideEffectsDetector);
+  }
+
+  const options = {
+    rootDirectoryUrl,
+    replaceFilesystemWellKnownValues,
+  };
+  let functionExecutingCount = 0;
+  const capture = (fn, { callSite, baseDirectory } = {}) => {
+    if (baseDirectory !== undefined && filesystemSideEffectsDetector) {
+      filesystemSideEffectsDetector.setBaseDirectory(baseDirectory);
+    }
+    const startMs = Date.now();
+    const sideEffects = [];
+    sideEffects.options = options;
+    const sideEffectTypeCounterMap = new Map();
+    const onSideEffectAdded = (sideEffect) => {
+      let counter = sideEffectTypeCounterMap.get(sideEffect.type) || 0;
+      sideEffectTypeCounterMap.set(sideEffect.type, counter + 1);
+      sideEffect.counter = counter;
+      sideEffect.delay = Date.now() - startMs;
+    };
+    const onSideEffectRemoved = () => {};
+    const addSideEffect = (sideEffect) => {
+      sideEffects.push(sideEffect);
+      onSideEffectAdded(sideEffect);
+      return sideEffect;
+    };
+    const replaceSideEffect = (existingSideEffect, newSideEffect) => {
+      const index = sideEffects.indexOf(existingSideEffect);
+      sideEffects[index] = newSideEffect;
+      onSideEffectRemoved(existingSideEffect);
+      onSideEffectAdded(newSideEffect);
+    };
+    const removeSideEffect = (sideEffect) => {
+      const index = sideEffects.indexOf(sideEffect);
+      if (index > -1) {
+        sideEffects.splice(index, 1);
+        onSideEffectRemoved(sideEffect);
+      }
+    };
+    sideEffects.replaceSideEffect = replaceSideEffect;
+    sideEffects.removeSideEffect = removeSideEffect;
+
+    const sourceCode = parseFunction(fn).body;
+    addSideEffect({
+      code: "source_code",
+      type: "source_code",
+      value: { sourceCode, callSite },
+      render: {
+        md: () => {
+          return {
+            type: "source_code",
+            text: {
+              type: "source_code",
+              value: { sourceCode, callSite },
+            },
+          };
+        },
+      },
+    });
+
+    const finallyCallbackSet = new Set();
+    const addFinallyCallback = (finallyCallback) => {
+      finallyCallbackSet.add(finallyCallback);
+    };
+    const skippableHandlerSet = new Set();
+    const addSkippableHandler = (skippableHandler) => {
+      skippableHandlerSet.add(skippableHandler);
+    };
+    addFinallyCallback((sideEffects) => {
+      let i = 0;
+      while (i < sideEffects.length) {
+        const sideEffect = sideEffects[i];
+        i++;
+        let skippableHandlerResult;
+        for (const skippableHandler of skippableHandlerSet) {
+          skippableHandlerResult = skippableHandler(sideEffect);
+          if (skippableHandlerResult) {
+            // there is no skippable per sideEffect type today
+            // so even if the skippable doe not skip in the end
+            // we don't have to check if an other skippable handler could
+            break;
+          }
+        }
+        if (skippableHandlerResult) {
+          let j = i;
+          while (j < sideEffects.length) {
+            const afterSideEffect = sideEffects[j];
+            j++;
+            let stopCalled = false;
+            let skipCalled = false;
+            const stop = () => {
+              stopCalled = true;
+            };
+            const skip = () => {
+              skipCalled = true;
+            };
+            skippableHandlerResult(afterSideEffect, { skip, stop });
+            if (skipCalled) {
+              sideEffect.skippable = true;
+              break;
+            }
+            if (stopCalled) {
+              break;
+            }
+          }
+        }
+      }
+    });
+    addSkippableHandler((sideEffect) => {
+      if (sideEffect.type === "return" && sideEffect.value === RETURN_PROMISE) {
+        return (nextSideEffect, { skip }) => {
+          if (
+            nextSideEffect.code === "resolve" ||
+            nextSideEffect.code === "reject"
+          ) {
+            skip();
+          }
+        };
+      }
+      return null;
+    });
+
+    for (const detector of detectors) {
+      const uninstall = detector.install(addSideEffect, {
+        addSkippableHandler,
+        addFinallyCallback,
+      });
+      finallyCallbackSet.add(() => {
+        uninstall();
+      });
+    }
+    if (functionExecutingCount) {
+      // The reason for this warning:
+      // 1. fs side effect detectors is not yet fully compatible with that because
+      //    callback.oncomplete redefinition might be wrong for open, mkdir etc
+      //    (at least this is to be tested)
+      // 2. It's usually a sign code forgets to put await in front of
+      //    collectFunctionSideEffects or snapshotFunctionSideEffects
+      // 3. collectFunctionSideEffects is meant to collect a function side effect
+      //    during unit test. So in unit test the function being tested should be analyized
+      //    and should not in turn analyze an other one
+      console.warn(
+        `captureSideEffects called while other function(s) side effects are collected`,
+      );
+    }
+
+    const onCatch = (valueThrow) => {
+      addSideEffect({
+        code: "throw",
+        type: "throw",
+        value: valueThrow,
+        render: {
+          md: () => {
+            return {
+              label: "throw",
+              text: {
+                type: "js_value",
+                value: valueThrow,
+              },
+            };
+          },
+        },
+      });
+    };
+    const onReturn = (valueReturned) => {
+      if (valueReturned === RETURN_PROMISE) {
+        addSideEffect({
+          code: "return",
+          type: "return",
+          value: valueReturned,
+          render: {
+            md: () => {
+              return {
+                label: "return promise",
+              };
+            },
+          },
+        });
+        return;
+      }
+      addSideEffect({
+        code: "return",
+        type: "return",
+        value: valueReturned,
+        render: {
+          md: () => {
+            return {
+              label: "return",
+              text: {
+                type: "js_value",
+                value: valueReturned,
+              },
+            };
+          },
+        },
+      });
+    };
+    const onResolve = (value) => {
+      addSideEffect({
+        code: "resolve",
+        type: "resolve",
+        value,
+        render: {
+          md: () => {
+            return {
+              label: "resolve",
+              text: {
+                type: "js_value",
+                value,
+              },
+            };
+          },
+        },
+      });
+    };
+    const onReject = (reason) => {
+      addSideEffect({
+        code: "reject",
+        type: "reject",
+        value: reason,
+        render: {
+          md: () => {
+            return {
+              label: "reject",
+              text: {
+                type: "js_value",
+                value: reason,
+              },
+            };
+          },
+        },
+      });
+    };
+    const onFinally = () => {
+      delete process.env.SNAPSHOTING_FUNCTION_SIDE_EFFECTS;
+      functionExecutingCount--;
+      for (const finallyCallback of finallyCallbackSet) {
+        finallyCallback(sideEffects);
+      }
+      finallyCallbackSet.clear();
+    };
+
+    process.env.SNAPSHOTING_FUNCTION_SIDE_EFFECTS = "1";
+    functionExecutingCount++;
+    let returnedPromise = false;
+    try {
+      const valueReturned = fn();
+      if (valueReturned && typeof valueReturned.then === "function") {
+        onReturn(RETURN_PROMISE);
+        returnedPromise = valueReturned.then(
+          (value) => {
+            onResolve(value);
+            onFinally();
+            return sideEffects;
+          },
+          (e) => {
+            onReject(e);
+            onFinally();
+            return sideEffects;
+          },
+        );
+        return returnedPromise;
+      }
+      onReturn(valueReturned);
+      return sideEffects;
+    } catch (e) {
+      onCatch(e);
+      return sideEffects;
+    } finally {
+      if (!returnedPromise) {
+        onFinally();
+      }
+    }
+  };
+  return capture;
+};
+
+const RETURN_PROMISE = {};