doc,test: improvements and cleanup for assert.snapshot()

doc/api/assert.md

@@ -2097,23 +2097,39 @@ added: v18.8.0
 
 > Stability: 1 - Experimental
 
-* `value` {any} the value to snapshot
-* `name` {string} the name of snapshot.
+* `value` {any} the value to snapshot.
+* `name` {string} the name of the 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`][].
+Reads the `name` 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()` returns a rejected `Promise` with an
+[`AssertionError`][].
+
+The snapshot filename uses the same basename as the application's main
+entrypoint with a `.snapshot` extension. If the snapshot file does not exist,
+it is created. The [`--update-assert-snapshot`][] command line flag can be used
+to force the update of an existing snapshot.
 
-If the snapshot file does not exist, the snapshot is written.
+```mjs
+import assert from 'node:assert/strict';
 
-In case it is needed to force a snapshot update,
-use [`--update-assert-snapshot`][];
+// Assuming that the application's main entrypoint is app.mjs, this reads the
+// 'snapshotName' snapshot from app.snapshot and strictly compares its value
+// to `util.inspect('value')`.
+await assert.snapshot('value', 'snapshotName');
+```
 
-By default, a snapshot is read and written to a file,
-using the same name as the main entrypoint with `.snapshot` as the extension.
+```cjs
+const assert = require('node:assert/strict');
+
+(async () => {
+  // Assuming that the application's main entrypoint is app.js, this reads the
+  // 'snapshotName' snapshot from app.snapshot and strictly compares its value
+  // to `util.inspect('value')`.
+  await assert.snapshot('value', 'snapshotName');
+})();
+```
 
 ## `assert.strictEqual(actual, expected[, message])`
 

doc/api/cli.md

@@ -1512,7 +1512,7 @@ loading phase, it will always raise it as an uncaught exception.
 added: v18.8.0
 -->
 
-Force updating snapshot files for [`assert.snapshot()`][]
+Updates snapshot files used by [`assert.snapshot()`][].
 
 ### `--use-bundled-ca`, `--use-openssl-ca`
 

doc/node.1

@@ -486,6 +486,9 @@ Track heap object allocations for heap snapshots.
 .It Fl -unhandled-rejections=mode
 Define the behavior for unhandled rejections. Can be one of `strict` (raise an error), `warn` (enforce warnings) or `none` (silence warnings).
 .
+.It Fl -update-assert-snapshot
+Updates snapshot files used by `assert.snapshot()`.
+.
 .It Fl -use-bundled-ca , Fl -use-openssl-ca
 Use bundled Mozilla CA store as supplied by current Node.js version or use OpenSSL's default CA store.
 The default store is selectable at build-time.

test/fixtures/assert-snapshot/basic.mjs

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

test/fixtures/assert-snapshot/multiple.mjs

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

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

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

test/fixtures/assert-snapshot/single.mjs

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

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

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