diff --git a/doc/api/assert.md b/doc/api/assert.md index 2b8eede2b87e57..4864023f65d290 100644 --- a/doc/api/assert.md +++ b/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])` diff --git a/doc/api/cli.md b/doc/api/cli.md index 798400ade85f1d..46f792979c4189 100644 --- a/doc/api/cli.md +++ b/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` diff --git a/doc/node.1 b/doc/node.1 index 2c179442ab2f41..50a80742c458f9 100644 --- a/doc/node.1 +++ b/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. diff --git a/test/fixtures/assert-snapshot/basic.mjs b/test/fixtures/assert-snapshot/basic.mjs index 7879b7924f98bd..760cabf21da3b7 100644 --- a/test/fixtures/assert-snapshot/basic.mjs +++ b/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'); diff --git a/test/fixtures/assert-snapshot/multiple.mjs b/test/fixtures/assert-snapshot/multiple.mjs index efb1e9ace51410..a8d21fdbd512ab 100644 --- a/test/fixtures/assert-snapshot/multiple.mjs +++ b/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'); diff --git a/test/fixtures/assert-snapshot/non-existing-name.mjs b/test/fixtures/assert-snapshot/non-existing-name.mjs index f98ec61c37be76..b05e6c840cbaa7 100644 --- a/test/fixtures/assert-snapshot/non-existing-name.mjs +++ b/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'); diff --git a/test/fixtures/assert-snapshot/single.mjs b/test/fixtures/assert-snapshot/single.mjs index ff0136388c08c6..99651ddfb62ccb 100644 --- a/test/fixtures/assert-snapshot/single.mjs +++ b/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'); diff --git a/test/fixtures/assert-snapshot/value-changed.mjs b/test/fixtures/assert-snapshot/value-changed.mjs index 5a09e0afcbd062..ee11b93e3305de 100644 --- a/test/fixtures/assert-snapshot/value-changed.mjs +++ b/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');