Commit ae028e8
doc: improve assert.snapshot() docs
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>1 parent 71c8696 commit ae028e8
2 files changed
Lines changed: 29 additions & 13 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2097,23 +2097,39 @@ added: v18.8.0 | |||
| 2097 | 2097 | ||
| 2098 | 2098 | > Stability: 1 - Experimental | |
| 2099 | 2099 | ||
| 2100 | - * `value` {any} the value to snapshot | ||
| 2101 | - * `name` {string} the name of snapshot. | ||
| 2100 | + * `value` {any} the value to snapshot. | ||
| 2101 | + * `name` {string} the name of the snapshot. | ||
| 2102 | 2102 | * Returns: {Promise} | |
| 2103 | 2103 | ||
| 2104 | - reads a snapshot from a file, and compares `value` to the snapshot. | ||
| 2105 | - `value` is serialized with [`util.inspect()`][] | ||
| 2106 | - If the value is not strictly equal to the snapshot, | ||
| 2107 | - `assert.snapshot()` will return a rejected `Promise` | ||
| 2108 | - with an [`AssertionError`][]. | ||
| 2104 | + Reads the `name` snapshot from a file and compares `value` to the snapshot. | ||
| 2105 | + `value` is serialized with [`util.inspect()`][]. If the value is not strictly | ||
| 2106 | + equal to the snapshot, `assert.snapshot()` returns a rejected `Promise` with an | ||
| 2107 | + [`AssertionError`][]. | ||
| 2108 | + | ||
| 2109 | + The snapshot filename uses the same basename as the application's main | ||
| 2110 | + entrypoint with a `.snapshot` extension. If the snapshot file does not exist, | ||
| 2111 | + it is created. The [`--update-assert-snapshot`][] command line flag can be used | ||
| 2112 | + to force the update of an existing snapshot. | ||
| 2109 | 2113 | ||
| 2110 | - If the snapshot file does not exist, the snapshot is written. | ||
| 2114 | + ```mjs | ||
| 2115 | + import assert from 'node:assert/strict'; | ||
| 2111 | 2116 | ||
| 2112 | - In case it is needed to force a snapshot update, | ||
| 2113 | - use [`--update-assert-snapshot`][]; | ||
| 2117 | + // Assuming that the application's main entrypoint is app.mjs, this reads the | ||
| 2118 | + // 'snapshotName' snapshot from app.snapshot and strictly compares its value | ||
| 2119 | + // to `util.inspect('value')`. | ||
| 2120 | + await assert.snapshot('value', 'snapshotName'); | ||
| 2121 | + ``` | ||
| 2114 | 2122 | ||
| 2115 | - By default, a snapshot is read and written to a file, | ||
| 2116 | - using the same name as the main entrypoint with `.snapshot` as the extension. | ||
| 2123 | + ```cjs | ||
| 2124 | + const assert = require('node:assert/strict'); | ||
| 2125 | + | ||
| 2126 | + (async () => { | ||
| 2127 | + // Assuming that the application's main entrypoint is app.js, this reads the | ||
| 2128 | + // 'snapshotName' snapshot from app.snapshot and strictly compares its value | ||
| 2129 | + // to `util.inspect('value')`. | ||
| 2130 | + await assert.snapshot('value', 'snapshotName'); | ||
| 2131 | + })(); | ||
| 2132 | + ``` | ||
| 2117 | 2133 | ||
| 2118 | 2134 | ## `assert.strictEqual(actual, expected[, message])` | |
| 2119 | 2135 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1464,7 +1464,7 @@ loading phase, it will always raise it as an uncaught exception. | |||
| 1464 | 1464 | added: v18.8.0 | |
| 1465 | 1465 | --> | |
| 1466 | 1466 | ||
| 1467 | - Force updating snapshot files for [`assert.snapshot()`][] | ||
| 1467 | + Updates snapshot files used by [`assert.snapshot()`][]. | ||
| 1468 | 1468 | ||
| 1469 | 1469 | ### `--use-bundled-ca`, `--use-openssl-ca` | |
| 1470 | 1470 | ||
0 commit comments