@jsenv/snapshot 2.15.9 → 2.15.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/snapshot",
-  "version": "2.15.9",
+  "version": "2.15.11",
   "description": "Snapshot testing",
   "license": "MIT",
   "author": {
@@ -32,13 +32,13 @@
   "sideEffects": false,
   "dependencies": {
     "@jsenv/assert": "4.5.3",
-    "@jsenv/ast": "6.7.1",
+    "@jsenv/ast": "6.7.3",
     "@jsenv/url-meta": "8.5.7",
     "@jsenv/exception": "1.2.1",
-    "@jsenv/humanize": "1.5.2",
-    "@jsenv/filesystem": "4.15.2",
-    "@jsenv/terminal-recorder": "1.5.17",
-    "@jsenv/urls": "2.7.4",
+    "@jsenv/humanize": "1.6.0",
+    "@jsenv/filesystem": "4.15.3",
+    "@jsenv/terminal-recorder": "1.5.20",
+    "@jsenv/urls": "2.8.0",
     "@jsenv/utils": "2.3.1",
     "ansi-regex": "6.1.0",
     "pixelmatch": "7.1.0",

package/readme.md

@@ -1,9 +1,33 @@
-# snapshot
+# @jsenv/snapshot
 
 [![npm package](https://img.shields.io/npm/v/@jsenv/snapshot.svg?logo=npm&label=package)](https://www.npmjs.com/package/@jsenv/snapshot)
 
 A powerful snapshot testing tool for JavaScript applications.
 
+📸 Create readable, reliable test snapshots  
+🔄 Document code behavior with markdown  
+📊 Track changes in code output over time  
+🧩 Normalize fluctuating values for stable comparisons
+
+## Table of Contents
+
+- [@jsenv/snapshot](#jsenvsnapshot)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction to Snapshot Testing](#introduction-to-snapshot-testing)
+  - [Installation](#installation)
+  - [How `@jsenv/snapshot` Works](#how-jsenvsnapshot-works)
+  - [API Reference](#api-reference)
+    - [snapshotTests(testFileUrl, fnRegisteringTests, options)](#snapshotteststestfileurl-fnregisteringtests-options)
+  - [when radius is 10](#when-radius-is-10)
+  - [when radius is null](#when-radius-is-null)
+    - [Why Use snapshotTests?](#why-use-snapshottests)
+    - [takeFileSnapshot(fileUrl)](#takefilesnapshotfileurl)
+    - [takeDirectorySnapshot(directoryUrl)](#takedirectorysnapshotdirectoryurl)
+  - [Stable Snapshots Across Environments](#stable-snapshots-across-environments)
+  - [Advanced Examples](#advanced-examples)
+  - [Compatibility](#compatibility)
+  - [Contributing](#contributing)
+
 ## Introduction to Snapshot Testing
 
 Snapshot testing is a technique that:
@@ -17,6 +41,12 @@ Snapshot testing is a technique that:
 
 This approach ensures your code continues to behave as expected by verifying its outputs remain consistent over time.
 
+## Installation
+
+```console
+npm install --save-dev @jsenv/snapshot
+```
+
 ## How `@jsenv/snapshot` Works
 
 When running tests:
@@ -26,10 +56,111 @@ When running tests:
   - In CI environments (`process.env.CI` is set): An error is thrown if differences are detected
   - Locally: No error is thrown, allowing you to review changes with tools like git diff
 
-> **Note**: All functions accept a throwWhenDiff parameter to force errors even in local environments.
+> **Note**: All functions accept a `throwWhenDiff` parameter to force errors even in local environments.
 
 ## API Reference
 
+### snapshotTests(testFileUrl, fnRegisteringTests, options)
+
+The most powerful feature of this library - creates readable markdown snapshots of test executions.
+
+```js
+import { snapshotTests } from "@jsenv/snapshot";
+
+const getCircleArea = (circleRadius) => {
+  if (isNaN(circleRadius)) {
+    throw new TypeError(
+      `circleRadius must be a number, received ${circleRadius}`,
+    );
+  }
+  return circleRadius * circleRadius * Math.PI;
+};
+
+await snapshotTests(import.meta.url, ({ test }) => {
+  test("when radius is 2", () => {
+    return getCircleArea(2);
+  });
+
+  test("when radius is 10", () => {
+    return getCircleArea(10);
+  });
+
+  test("when radius is null", () => {
+    try {
+      return getCircleArea(null);
+    } catch (e) {
+      return e;
+    }
+  });
+});
+```
+
+This generates a markdown file documenting how your code behaves in different scenarios:
+
+````markdown
+# getCircleArea
+
+## when radius is 2
+
+```js
+getCircleArea(2);
+```
+````
+
+Returns:
+
+```js
+12.566370614359172;
+```
+
+## when radius is 10
+
+```js
+getCircleArea(10);
+```
+
+Returns:
+
+```js
+314.1592653589793;
+```
+
+## when radius is null
+
+```js
+getCircleArea(null);
+```
+
+Throws:
+
+```
+TypeError: circleRadius must be a number, received null
+```
+
+````
+
+See a full example at [./docs/\_circle_area.test.js/circle_area.test.js.md](./docs/_circle_area.test.js/circle_area.test.js.md)
+
+#### snapshotTests Options
+
+```js
+await snapshotTests(import.meta.url, fnRegisteringTests, {
+  throwWhenDiff: true, // Force error on snapshot differences (default: false in local, true in CI)
+  formatValue: (value) => {}, // Custom formatter for values
+  trackingConfig: {}, // Track specific resources like network requests or file operations
+});
+````
+
+#### Why Use snapshotTests?
+
+- **Assertion-free testing**: Simply call your functions and let the snapshots document their behavior
+- **Self-documenting tests**: Markdown files serve as both test validation and documentation
+- **Visual change reviews**: Code changes are reflected in snapshots, making reviews easy
+- **Side effect tracking**: Automatically captures and documents:
+  - Console logs ([example](./docs/_log.test.js/log.test.js.md))
+  - Filesystem operations ([example](./docs/_filesystem.test.js/filesystem.test.js.md))
+  - And more
+
 ### takeFileSnapshot(fileUrl)
 
 Captures and compares the state of a specific file.
@@ -40,7 +171,7 @@ import { takeFileSnapshot } from "@jsenv/snapshot";
 
 const fileTxtUrl = new URL("./file.txt", import.meta.url);
 const writeFileTxt = (content) => {
-  writeFileSync(writeFileTxt, content);
+  writeFileSync(fileTxtUrl, content);
 };
 
 // take snapshot of "./file.txt"
@@ -66,66 +197,22 @@ const writeManyFiles = () => {
 
 // take snapshot of "./dir/"
 const directorySnapshot = takeDirectorySnapshot(directoryUrl);
-writeFileTxt(directoryUrl);
+writeManyFiles();
 // compare the state of "./dir/" with previous version
 directorySnapshot.compare();
 ```
 
-### snapshotTests(testFileUrl, fnRegistertingTests, options)
-
-The most powerful feature of this library - creates readable markdown snapshots of test executions.
-
-```js
-import { snapshotTests } from "@jsenv/snapshot";
-
-const getCircleArea = (circleRadius) => {
-  if (isNaN(circleRadius)) {
-    throw new TypeError(
-      `circleRadius must be a number, received ${circleRadius}`,
-    );
-  }
-  return circleRadius * circleRadius * Math.PI;
-};
-
-await snapshotTests(import.meta.url, ({ test }) => {
-  test("when radius is 2", () => {
-    return getCircleArea(2);
-  });
-
-  test("when radius is 10", () => {
-    return getCircleArea(10);
-  });
-
-  test("when radius is null", () => {
-    return getCircleArea(null);
-  });
-});
-```
-
-This generates a markdown file documenting how your code behaves in different scenarios.
-See an example at [./docs/\_circle_area.test.js/circle_area.test.js.md](./docs/_circle_area.test.js/circle_area.test.js.md)
-
-## Why Use snapshotTests?
-
-- **Assertion-free testing**: Simply call your functions and let the snapshots document their behavior
-- **Self-documenting tests**: Markdown files serve as both test validation and documentation
-- **Visual change reviews**: Code changes are reflected in snapshots, making reviews easy
-- **Side effect tracking**: Automatically captures and documents:
-
-  - Console logs [example](./docs/_log.test.js/log.test.js.md)
-  - Filesystem operations [example](./docs/_filesystem.test.js/filesystem.test.js.md)
-  - And more
-
-- Fluctuating values are replaced with stable values, see [#Fluctuating values replacement](#fluctuating-values-replacement)
-
 ## Stable Snapshots Across Environments
 
 To ensure snapshots remain consistent across different machines and CI environments, `@jsenv/snapshot` automatically normalizes fluctuating values:
 
-- Time values like "2s" become "Xs"
-- Filesystem paths are standardized
-- Network ports in URLs are removed
-- And much more...
+| Fluctuating Value | Stabilized As                 |
+| ----------------- | ----------------------------- |
+| Time durations    | `"Xs"` instead of `"2.34s"`   |
+| Filesystem paths  | Platform-independent paths    |
+| Network ports     | Removed from URLs             |
+| Random IDs        | Consistent placeholder values |
+| Stack traces      | Simplified and normalized     |
 
 This ensures your snapshot tests remain stable regardless of when or where they run.
 
@@ -134,6 +221,12 @@ This ensures your snapshot tests remain stable regardless of when or where they
 - Testing complex assertion behavior: [@jsenv/assert/tests/array.test.js.md](../assert/tests/_array.test.js/array.test.js.md)
 - Testing server-side builds with browser execution: [@jsenv/core/tests/script_type_module_basic.test.mjs](../../../tests/build/basics/script_type_module_basic/_script_type_module_basic.test.mjs/script_type_module_basic.test.mjs.md)
 
+## Compatibility
+
+- Node.js: 16.x and above
+- Works with most JavaScript test runners
+- Compatible with ESM and CommonJS modules
+
 ## Contributing
 
 If you encounter unstable snapshots due to fluctuating values not being properly normalized, please open an issue or submit a pull request.