Skip to content

Commit

Permalink
doc: improve assert.snapshot() docs
Browse files Browse the repository at this point in the history
PR-URL: #44429
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
  • Loading branch information
cjihrig authored and RafaelGSS committed Sep 6, 2022
1 parent 82700b4 commit d6ac16a
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 13 deletions.
40 changes: 28 additions & 12 deletions doc/api/assert.md
Original file line number Diff line number Diff line change
Expand Up @@ -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])`

Expand Down
2 changes: 1 addition & 1 deletion doc/api/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand Down

0 comments on commit d6ac16a

Please sign in to comment.