assert: add snapshot assertion

doc/api/assert.md

@@ -2006,6 +2006,32 @@ argument, then `error` is assumed to be omitted and the string will be used for
 example in [`assert.throws()`][] carefully if using a string as the second
 argument gets considered.
 
+## `assert.snapshot(value, name)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+* `value` {any} the value to snapshot
+* `name` {string} the name of snapshot.
+* Returns: {Promise}
+
+reads a snapshot from a file, and compares `value` to the snapshot.
+`value` is serialized with [`util.inspect()`][]
+If the value is not strictly equal to the snapshot,
+`assert.snapshot()` will return a rejected `Promise`
+with an [`AssertionError`][].
+
+If the snapshot file does not exist, the snapshot is written.
+
+In case it is needed to force a snapshot update,
+set `process.env.NODE_UPDATE_SNAPSHOT=1`;
+
+By default, a snapshot is read and written to a file,
+using the same name as the main entrypoint with `.snapshot` as the extension.
+
 ## `assert.strictEqual(actual, expected[, message])`
 
 <!-- YAML
@@ -2473,5 +2499,6 @@ argument.
 [`process.on('exit')`]: process.md#event-exit
 [`tracker.calls()`]: #trackercallsfn-exact
 [`tracker.verify()`]: #trackerverify
+[`util.inspect()`]: util.md#utilinspectobject-options
 [enumerable "own" properties]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties
 [prototype-spec]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots

doc/api/errors.md

@@ -705,6 +705,13 @@ A special type of error that can be triggered whenever Node.js detects an
 exceptional logic violation that should never occur. These are raised typically
 by the `node:assert` module.
 
+<a id="ERR_ASSERT_SNAPSHOT_NOT_SUPPORTED"></a>
+
+### `ERR_ASSERT_SNAPSHOT_NOT_SUPPORTED`
+
+An attempt was made to use `assert.snapshot()` in an environment that
+does not support snapshots, such as the REPL, or when using `node --eval`.
+
 <a id="ERR_ASYNC_CALLBACK"></a>
 
 ### `ERR_ASYNC_CALLBACK`

lib/assert.js

@@ -1052,6 +1052,9 @@ assert.doesNotMatch = function doesNotMatch(string, regexp, message) {
 
 assert.CallTracker = CallTracker;
 
+const snapshot = require('internal/assert/snapshot');
+assert.snapshot = snapshot;
+
 /**
  * Expose a strict only variant of assert.
  * @param {...any} args

lib/internal/assert/snapshot.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const {
+  ArrayPrototypeMap,
+  Boolean,
+  RegExp,
+  SafeMap,
+  SafeSet,
+  StringPrototypeIndexOf,
+  StringPrototypeSlice,
+  StringPrototypeSplit,
+  StringPrototypeReplace,
+  Symbol,
+} = primordials;
+
+const { EOL } = require('internal/constants');
+const { codes: { ERR_ASSERT_SNAPSHOT_NOT_SUPPORTED } } = require('internal/errors');
+const AssertionError = require('internal/assert/assertion_error');
+const { inspect } = require('internal/util/inspect');
+const { validateString } = require('internal/validators');
+const { once } = require('events');
+const { createReadStream, createWriteStream } = require('fs');
+const path = require('path');
+const assert = require('assert');
+
+const kUpdateSnapshot = Boolean(process.env.NODE_UPDATE_SNAPSHOT);
+const kInitialSnapshot = Symbol('kInitialSnapshot');
+const kDefaultDelimiter = '\n#*#*#*#*#*#*#*#*#*#*#*#\n';
+const kDefaultDelimiterRegex = new RegExp(kDefaultDelimiter.replaceAll('*', '\\*').replaceAll('\n', '\r?\n'), 'g');
+
+function getSnapshotPath() {
+  if (process.mainModule) {
+    const { dir, name } = path.parse(process.mainModule.filename);
+    return path.join(dir, `${name}.snapshot`);
+  }
+  if (!process.argv[1]) {
+    throw new ERR_ASSERT_SNAPSHOT_NOT_SUPPORTED();
+  }
+  const { dir, name } = path.parse(process.argv[1]);
+  return path.join(dir, `${name}.snapshot`);
+}
+
+function getSource() {
+  return createReadStream(getSnapshotPath(), { encoding: 'utf8' });
+}
+
+let _target;
+function getTarget() {
+  _target ??= createWriteStream(getSnapshotPath(), { encoding: 'utf8' });
+  return _target;
+}
+
+function serializeName(name) {
+  validateString(name, 'name');
+  return StringPrototypeReplace(`${name}`, /:\r?\n/g, '_');
+}
+
+let writtenNames;
+let snapshotValue;
+let counter = 0;
+
+async function writeSnapshot({ name, value }) {
+  const target = getTarget();
+  if (counter > 1) {
+    target.write(kDefaultDelimiter);
+  }
+  writtenNames = writtenNames || new SafeSet();
+  if (writtenNames.has(name)) {
+    throw new AssertionError({ message: `Snapshot "${name}" already used` });
+  }
+  writtenNames.add(name);
+  const drained = target.write(`${name}:\n${value}`);
+  await drained || once(target, 'drain');
+}
+
+async function getSnapshot() {
+  if (snapshotValue !== undefined) {
+    return snapshotValue;
+  }
+  if (kUpdateSnapshot) {
+    snapshotValue = kInitialSnapshot;
+    return kInitialSnapshot;
+  }
+  try {
+    const source = getSource();
+    let data = '';
+    for await (const line of source) {
+      data += line;
+    }
+    snapshotValue = new SafeMap(
+      ArrayPrototypeMap(
+        StringPrototypeSplit(data, kDefaultDelimiterRegex),
+        (item) => {
+          const keyDelimiter = StringPrototypeIndexOf(item, `:${EOL}`);
+          return [StringPrototypeSlice(item, 0, keyDelimiter), StringPrototypeSlice(item, keyDelimiter + 2)];
+        }
+      ));
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      snapshotValue = kInitialSnapshot;
+    } else {
+      throw e;
+    }
+  }
+  return snapshotValue;
+}
+
+
+async function snapshot(input, name) {
+  const snapshot = await getSnapshot();
+  counter = counter + 1;
+  name = serializeName(name);
+
+  const value = inspect(input);
+  if (snapshot === kInitialSnapshot) {
+    await writeSnapshot({ name, value });
+  } else if (snapshot.has(name)) {
+    const expected = snapshot.get(name);
+    // eslint-disable-next-line no-restricted-syntax
+    assert.strictEqual(value, expected);
+  } else {
+    throw new AssertionError({ message: `Snapshot "${name}" does not exist` });
+  }
+}
+
+module.exports = snapshot;

lib/internal/errors.js

@@ -936,6 +936,8 @@ module.exports = {
 E('ERR_AMBIGUOUS_ARGUMENT', 'The "%s" argument is ambiguous. %s', TypeError);
 E('ERR_ARG_NOT_ITERABLE', '%s must be iterable', TypeError);
 E('ERR_ASSERTION', '%s', Error);
+E('ERR_ASSERT_SNAPSHOT_NOT_SUPPORTED',
+  'Snapshot is not supported in this context ', TypeError);
 E('ERR_ASYNC_CALLBACK', '%s must be a function', TypeError);
 E('ERR_ASYNC_TYPE', 'Invalid name for async "type": %s', TypeError);
 E('ERR_BROTLI_INVALID_PARAM', '%s is not a valid Brotli parameter', RangeError);

test/fixtures/assert-snapshot/basic.mjs

@@ -0,0 +1,3 @@
+import assert from 'node:assert';
+
+await assert.snapshot("test", "name");

test/fixtures/assert-snapshot/basic.snapshot

@@ -0,0 +1,2 @@
+name:
+'test'

test/fixtures/assert-snapshot/multiple.mjs

@@ -0,0 +1,4 @@
+import assert from 'node:assert';
+
+await assert.snapshot("test", "name");
+await assert.snapshot("test", "another name");

test/fixtures/assert-snapshot/multiple.snapshot

@@ -0,0 +1,5 @@
+name:
+'test'
+#*#*#*#*#*#*#*#*#*#*#*#
+another name:
+'test'

test/fixtures/assert-snapshot/non-existing-name.mjs

@@ -0,0 +1,4 @@
+import assert from 'node:assert';
+
+await assert.snapshot("test", "another name");
+await assert.snapshot("test", "non existing");

test/fixtures/assert-snapshot/non-existing-name.snapshot

@@ -0,0 +1,5 @@
+another name:
+'test'
+#*#*#*#*#*#*#*#*#*#*#*#
+name:
+'test'

test/fixtures/assert-snapshot/random.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert';
+
+function random() {
+  return `Random Value: ${Math.random()}`;
+}
+function transform(value) {
+  return value.replaceAll(/Random Value: \d+\.+\d+/g, 'Random Value: *');
+}
+
+await assert.snapshot(transform(random()), 'random1');
+await assert.snapshot(transform(random()), 'random2');

test/fixtures/assert-snapshot/random.snapshot

@@ -0,0 +1,5 @@
+random1:
+'Random Value: *'
+#*#*#*#*#*#*#*#*#*#*#*#
+random2:
+'Random Value: *'

test/fixtures/assert-snapshot/serialize.mjs

@@ -0,0 +1,11 @@
+import assert from 'node:assert';
+
+function fn() {
+  this.should.be.a.fn();
+  return false;
+}
+
+await assert.snapshot(fn, 'function');
+await assert.snapshot({ foo: "bar" }, 'object');
+await assert.snapshot(new Set([1, 2, 3]), 'set');
+await assert.snapshot(new Map([['one', 1], ['two', 2]]), 'map');

test/fixtures/assert-snapshot/serialize.snapshot

@@ -0,0 +1,11 @@
+function:
+[Function: fn]
+#*#*#*#*#*#*#*#*#*#*#*#
+object:
+{ foo: 'bar' }
+#*#*#*#*#*#*#*#*#*#*#*#
+set:
+Set(3) { 1, 2, 3 }
+#*#*#*#*#*#*#*#*#*#*#*#
+map:
+Map(2) { 'one' => 1, 'two' => 2 }

test/fixtures/assert-snapshot/single.mjs

@@ -0,0 +1,3 @@
+import assert from 'node:assert';
+
+await assert.snapshot("test", "snapshot");

test/fixtures/assert-snapshot/single.snapshot

@@ -0,0 +1,2 @@
+snapshot:
+'test'

test/fixtures/assert-snapshot/value-changed.mjs

@@ -0,0 +1,3 @@
+import assert from 'node:assert';
+
+await assert.snapshot("changed", "snapshot");

test/fixtures/assert-snapshot/value-changed.snapshot

@@ -0,0 +1,2 @@
+snapshot:
+'original'