Verify returned values and nested result structures
Unit and integration tests
Node.js · Module
node:assert
The node:assert module provides built-in assertion functions for checking invariants. Prefer the strict entry point for non-coercive equality and deep comparisons.
How it works
The node:assert module exposes assertion functions that throw when expected conditions fail. Importing node:assert/strict selects strict behavior, including strict equality and deep comparisons; synchronous functions are checked directly, while assert.rejects() awaits a promise or an async function and verifies rejection.
Syntax
import assert from 'node:assert/strict';
assert.ok(value[, message]);
assert.strictEqual(actual, expected[, message]);
assert.deepStrictEqual(actual, expected[, message]);
assert.rejects(asyncFn[, error][, message]);Parameters
| Name | Type | Description |
|---|---|---|
value / actual | any | Value or actual input being checked; exact meaning depends on the assertion method. |
expected / error | any | Expected value, error, regular expression, or validation object, depending on the assertion method. |
message | string | Error | Optional message or Error used when an assertion fails. |
fn / asyncFn | Function | Promise | Function or promise supplied to synchronous or asynchronous throw/rejection assertions. |
Returns
Assertion functions return undefined on success and throw an AssertionError when the assertion fails.
Key points
- Use this built-in module to verify assumptions in tests and other code paths.
assert.ok(value)succeeds for truthy values and throws anAssertionErrorotherwise.deepStrictEqual(actual, expected)compares nested structures rather than only object identity.- Calling the module itself as
assert(value)is equivalent toassert.ok(value). assert.doesNotThrow()verifies that invoking a function completes without throwing.assert.rejects()accepts either an existing promise or an async function and waits for completion before checking rejection.
Common mistakes
- Use the strict entry point when you want non-strict method names such as
deepEqual()to apply strict semantics. - Avoid legacy
deepEqual()when exact type and value comparison is intended; usedeepStrictEqual(). assert.rejects()is for asynchronous rejection; it waits for the promise before evaluating the expected error.
Example: Strict assertions for synchronous and asynchronous results
import assert from 'node:assert/strict';
const result = { status: 200, body: { ok: true } };
assert.strictEqual(result.status, 200);
assert.deepStrictEqual(result.body, { ok: true });
assert.ok(result.body.ok);
await assert.rejects(
Promise.reject(new TypeError('bad input')),
TypeError
);This runnable ES module checks primitive equality, recursively compares object structure, verifies truthiness, and confirms that a promise rejects with the expected error type.
When to use it
Confirm promises reject with the intended error type
Async error-path tests
Fail fast when required conditions are not truthy
Runtime invariant checks
Interview questions
QHow do strictEqual() and deepStrictEqual() differ?
assert.strictEqual() compares values with strict equality, while assert.deepStrictEqual() recursively compares object contents using strict rules. Both throw an AssertionError when the assertion fails.
Follow-up: When would assert.deepStrictEqual() still distinguish two objects that look similar? It also compares relevant type tags and object prototypes, not only enumerable property values.
QHow do you test an expected asynchronous failure?
assert.rejects() awaits the supplied promise, or calls an async function and awaits its returned promise. It then verifies that rejection occurred and can additionally match the expected error.
Follow-up: What should be used for a synchronous function that must throw? Use assert.throws(), which checks that invoking the function throws.
QHow do you enable strict assertion mode?
The module can be imported through node:assert/strict or by selecting the strict export from node:assert. In strict mode, non-strict methods use the behavior of their strict counterparts.
Follow-up: Why prefer the strict entry point? It avoids accidentally getting legacy coercive behavior from methods such as equal() or deepEqual().
Related
AssertionErrorassert.ok()assert.strictEqual()assert.deepStrictEqual()assert.throws()assert.rejects()assert.doesNotThrow()assert.doesNotReject()