diff --git a/doc/api/cli.md b/doc/api/cli.md index 52108fd7ab2e91..8f6242a16c66e6 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -991,6 +991,16 @@ added: REPLACEME Enable module mocking in the test runner. +### `--experimental-test-snapshots` + + + +> Stability: 1.0 - Early development + +Enable [snapshot testing][] in the test runner. + ### `--experimental-vm-modules` + +> Stability: 1.0 - Early development + +Regenerates the snapshot file used by the test runner for [snapshot testing][]. +Node.js must be started with the `--experimental-test-snapshots` flag in order +to use this functionality. + ### `--throw-deprecation` + +> Stability: 1.0 - Early development + +An object whose methods are used to configure global test runner settings in the +current process. It is possible to apply the same configuration to all files by +placing common configuration code in a module preloaded with `--require` or +`--import`. + +### `config.setDefaultSnapshotSerializers(serializers)` + + + +> Stability: 1.0 - Early development + +* `serializers` {Array} An array of synchronous functions used as the default + serializers for snapshot tests. + +This function is used to customize the default serialization mechanism used by +the test runner. By default, the test runner performs serialization by calling +`JSON.stringify(value, null, 2)` on the provided value. `JSON.stringify()` does +have limitations regarding circular structures and supported data types. If a +more robust serialization mechanism is required, this function should be used. + +### `config.setResolveSnapshotPath(fn)` + + + +> Stability: 1.0 - Early development + +* `fn` {Function} A function used to compute the location of the snapshot file. + The function receives the path of the test file as its only argument. If the + `process.argv[1]` is not associated with a file (for example in the REPL), + the input is undefined. `fn()` must return a string specifying the location of + the snapshot file. + +This function is used to customize the location of the snapshot file used for +snapshot testing. By default, the snapshot filename is the same as the entry +point filename with a `.snapshot` file extension. + ## Class: `MockFunctionContext` + +> Stability: 1.0 - Early development + +* `value` {any} A value to serialize to a string. If Node.js was started with + the [`--test-update-snapshots`][] flag, the serialized value is written to + the snapshot file. Otherwise, the serialized value is compared to the + corresponding value in the existing snapshot file. +* `options` {Object} Optional configuration options. The following properties + are supported: + * `serializers` {Array} An array of synchronous functions used to serialize + `value` into a string. `value` is passed as the only argument to the first + serializer function. The return value of each serializer is passed as input + to the next serializer. Once all serializers have run, the resulting value + is coerced to a string. **Default:** If no serializers are provided, the + test runner's default serializers are used. + +This function implements assertions for snapshot testing. + +```js +test('snapshot test with default serialization', (t) => { + t.assert.snapshot({ value1: 1, value2: 2 }); +}); + +test('snapshot test with custom serialization', (t) => { + t.assert.snapshot({ value3: 3, value4: 4 }, { + serializers: [(value) => JSON.stringify(value)] + }); +}); +``` + ### `context.diagnostic(message)`