Node.js Reference ยท util, assert and the Test Runner
Snapshot testing in the Node.js test runner
Reference for snapshot testing in node:test: t.assert.snapshot(), the .snapshot file, --test-update-snapshots, custom serializers and snapshot paths.
A snapshot test stores the output of your code the first time it runs and compares every later run with that stored copy. If the output changes, the test fails and shows the difference. You then decide whether the change is a bug (fix the code) or intended (update the snapshot).
In node:test, snapshots are an assertion on the test context: t.assert.snapshot(value). The value is turned into a string by a serializer (JSON with two-space indentation by default) and compared with the entry saved in a .snapshot file next to your test file. Snapshots suit large, structured output such as generated HTML, rendered reports, parsed syntax trees or API response shapes, where writing the expected value by hand would be tedious.
import { test } from 'node:test'; test('renders the invoice', (t) => { t.assert.snapshot({ number: 7, lines: [{ item: 'pen', qty: 2 }] }); });
Try it
The helper writes a test file and runs it with run(). Passing execArgv: ['--test-update-snapshots'] is the same as running node --test --test-update-snapshots in a terminal: it creates or rewrites the snapshot file.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
t.assert.snapshot(value[, options]) import { snapshot } from 'node:test'; snapshot.setDefaultSnapshotSerializers(serializers) snapshot.setResolveSnapshotPath(fn)
| Name | Description |
|---|---|
value |
Any value. It is passed through the serializers to produce a string. |
options.serializers |
Array of functions (value) => any applied in order. The last result must be a string. Overrides the default serializers for this assertion. |
setDefaultSnapshotSerializers(list) |
Serializers used by every snapshot in the file unless an assertion supplies its own. |
setResolveSnapshotPath(fn) |
fn(testFilePath) returns the path of the snapshot file. Default: the test file path plus .snapshot. |
Command line. node --test --test-update-snapshots creates and rewrites snapshot files. Without the flag, a missing snapshot file fails the test and the message says how to generate it.
File format. One entry per assertion, named from the test's full name and a counter (values 1, values 2), in a JavaScript-like file that is easy to read in a code review:
exports[`order summary 1`] = `
{
"id": 7,
...
}
`;
Errors: a mismatch fails the test with an AssertionError showing + actual - expected.
Usage notes
- Commit the
.snapshotfiles and review them like code. A snapshot that changes in a pull request is the whole point of the technique. - Update deliberately. Run with
--test-update-snapshotsonly after you have read the diff. Updating blindly turns every regression into the new expected value. - Keep output deterministic. Timestamps, random IDs and absolute paths make snapshots fail at random. Replace them before snapshotting, or use assert.partialDeepStrictEqual() for the stable part.
- Keep snapshots small. A 500-line snapshot is hard to review and nobody reads it. Snapshot the part that matters.
- Names matter. Entries are keyed by test name plus counter. Renaming a test or reordering assertions inside it leaves an orphaned entry and a missing one.
- Not a replacement for assertions. A snapshot says "this equals what it was", not "this is right". Pair it with a few explicit assertions for the behavior you care about.
- Version notes.
t.assert.snapshot()was added in Node.js 22.3 and is newer than the rest of the assertion API, so check the stability note of the release you target.