diff options
author | cjihrig <cjihrig@gmail.com> | 2022-08-28 21:59:28 +0300 |
---|---|---|
committer | RafaelGSS <rafael.nunu@hotmail.com> | 2022-09-07 15:20:51 +0300 |
commit | ae028e8ac380afa916b74802ab52810bf7a457e3 (patch) | |
tree | 217a1533b69ab0ea7cd90cd0408ff42a7e8baf87 /doc | |
parent | 71c869688a62528ea60a41145d3d1821a9069034 (diff) |
doc: improve assert.snapshot() docs
PR-URL: https://github.com/nodejs/node/pull/44429
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/assert.md | 40 | ||||
-rw-r--r-- | doc/api/cli.md | 2 |
2 files changed, 29 insertions, 13 deletions
diff --git a/doc/api/assert.md b/doc/api/assert.md index 2b8eede2b87..4864023f65d 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 4f9d98a2344..d252aba1612 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -1464,7 +1464,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` |