Documentation tests with deno test --doc
deno test --doc runs the code examples inside JSDoc comments and markdown files as tests, so documentation can't silently go stale.
testing
78 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
Test sanitizers
The test runner can catch misbehavior that assertions don't see: leaked async operations, unclosed resources, and unexpected Deno.exit() calls. The exit sanitizer is on by default; the op and resource sanitizers are opt-in since Deno 2.8.
Test permissions configuration
The permissions property in the Deno.test configuration allows you to specifically deny permissions, but does not grant them. Permissions must be provided when running the test command. The permissions object supports detailed configuration including: read (true, false, or array of paths), write (true or false), net (true, false, or array of host:port combinations), env (true, false, or array of env variable names), run (true or false), ffi (true or false), and hrtime (true or false). Remember that any permission not explicitly granted at the command line will be denied, regardless of what's specified in the test configuration.
Test permissions permission inheritance
When no permissions property is specified in a test definition, it means the test inherits the permissions provided when running the test command.
Mocking and test doubles with @std/testing
Isolate the code under test by replacing its collaborators with spies, stubs, and mocks from @std/testing, and control the clock with FakeTime.
Snapshot testing overview and purpose
Snapshot testing captures the output of code and compares it against a stored reference version on every test run. Instead of hand-writing assertions for each property, the test runner records the entire serialized output once, then fails when that output changes. This is ideal for large or hard-to-express values like rendered HTML, CLI output, API response shapes, or error objects, and when expected output changes frequently.
t.assertSnapshot method for snapshot testing
Deno's built-in test runner provides snapshot testing through the t.assertSnapshot method on the test context, with no imports or dependencies. The method serializes a value and compares it against a reference snapshot stored alongside the test file, using the test name to key the snapshot.
Create and update snapshots with --update-snapshots flag
Snapshots are created and updated with the deno test --update-snapshots flag, which has the short form -u. The runner manages snapshot files itself, so no read or write permission is needed for snapshots in the default location. Any snapshot that does not match current output is rewritten, any missing snapshot is created, and snapshots that already match are left untouched.
Snapshot file location and naming
Snapshots are written to a __snapshots__ directory next to the test file, in a .snap file named after the test module. For example, test file example_test.ts produces snapshots in __snapshots__/example_test.ts.snap. Each snapshot entry is keyed by the test name plus a counter, so a test that calls assertSnapshot multiple times produces keys like isSnapshotMatch 1, isSnapshotMatch 2, and so on.
Snapshot serialization and format
Values are serialized using Deno.inspect with object keys sorted alphabetically. Snapshot files are plain TypeScript, making them easy to read in code review. Snapshot files should be committed to version control so snapshot changes are reviewed alongside code changes and anyone who pulls the branch gets passing tests without regenerating snapshots locally.
t.assertSnapshot options object parameters
t.assertSnapshot accepts an options object as its second argument with the following options: serializer (a deterministic function that turns the value into a string, used to strip ANSI codes, replace timestamps/UUIDs, or redact sensitive data), name (overrides the snapshot key, which otherwise defaults to the test name), dir and path (control where the snapshot file is written, resolved relative to the test file; a custom location requires read and write permission), and mode (force 'assert' or 'update' behavior for a single call, regardless of the --update-snapshots flag).
Custom serialization with Symbol.for("Deno.customInspect")
Classes can customize their own serialization by implementing Symbol.for("Deno.customInspect"), since the default serializer is built on Deno.inspect.
Example of snapshot test with custom serializer
import { stripAnsiCode } from "jsr:@std/fmt/colors"; Deno.test("Custom Serializer", async (t) => { const output = "\x1b[34mHello World!\x1b[39m"; await t.assertSnapshot(output, { serializer: (actual) => stripAnsiCode(actual), }); });
Example of basic snapshot test
Deno.test("isSnapshotMatch", async (t) => { const a = { hello: "world!", example: 123, }; await t.assertSnapshot(a); });
Node.js test module snapshot assertion
If you write tests with node:test instead of Deno.test, its own snapshot assertion t.assert.fileSnapshot is available. This method serializes a value, writes it to a named file the first time, and compares against that file on later runs.
Example of node:test snapshot assertion
import { test } from "node:test"; test("matches the saved output", (t) => { t.assert.fileSnapshot({ id: 1, name: "ada" }, "./__snapshots__/user.json"); });
When not to use snapshot testing
Snapshot tests assert that output has not changed, not that it is correct. They are a poor fit when: a precise assertion is easy to write (assertEquals documents intent better), the output is non-deterministic (timestamps, random IDs, unordered collections cause flaky failures), the output is huge (multi-thousand-line snapshots get rubber-stamped), or the test should verify behavior rather than representation (couples test to formatting details). Use snapshots where a human can meaningfully review the recorded output, and explicit assertions everywhere else.
Verify snapshots in CI without updating
In CI, run tests without the --update-snapshots flag to verify snapshots and never update them. If a pull request changes output, the CI run fails and the author must update snapshots locally and commit the new .snap files. Reviewers then see the exact before-and-after output in the pull request diff and can confirm the change is intentional.