Node.js Reference ยท util, assert and the Test Runner
Node.js AssertionError class
Reference for assert.AssertionError in Node.js: the error thrown by failed assertions, its actual, expected, operator, code and diff properties and how to catch it.
assert.AssertionError is the error class thrown whenever an assertion in node:assert fails. It extends Error and adds fields that describe the comparison: the two values, the operator that was used and the code 'ERR_ASSERTION'. Test runners read these fields to print a readable diff.
You rarely construct one yourself. You catch it, inspect it, or let it fail a test. Constructing one is useful when you write your own assertion helper and want failures to look like the built-in ones.
import assert from 'node:assert'; try { assert.strictEqual(1, 2); } catch (error) { console.log(error instanceof assert.AssertionError); }
Try it
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
new assert.AssertionError(options)
| Option | Description |
|---|---|
message |
If given, it becomes the error message and generatedMessage is false. Otherwise Node builds a message from the values and the operator. |
actual |
The value stored in error.actual. |
expected |
The value stored in error.expected. |
operator |
A string stored in error.operator, such as 'strictEqual'. |
stackStartFn |
A function: stack frames above (and including) it are removed, so the trace starts at your caller. |
diff |
How a diff is rendered in the message. 'simple' is the default and 'full' shows the whole comparison; available in recent Node.js releases. |
Instance properties
| Property | Description |
|---|---|
name |
Always 'AssertionError'. |
code |
Always 'ERR_ASSERTION'. |
message |
The text, usually with a + actual - expected diff for object comparisons. |
actual, expected |
The compared values, exactly as passed. |
operator |
The assertion that failed, for example 'deepStrictEqual', 'throws' or 'fail'. |
generatedMessage |
true when Node wrote the message, false when you supplied one. |
diff |
The diff style that was used, 'simple' or 'full'. |
Usage notes
- Check by class or by code.
error instanceof assert.AssertionErroranderror.code === 'ERR_ASSERTION'are both reliable. The class check does not work across separate copies of Node internals such as worker threads, where the code check is safer. - Custom messages. Passing a string as the last argument of any assertion sets
messageandgeneratedMessage: false. Passing anErrorinstance throws that error unchanged, so it is not anAssertionError. assert.fail(). Called with no arguments, the message isFailed. Itsoperatoris'fail'.- Large objects. The message includes an indented diff. Long unchanged stretches are collapsed so the changes stay visible. Printing
error.actualanderror.expectedyourself gives you the raw values. - Do not catch it to hide failures. Catching an
AssertionErrorin application code makes bugs silent. Catch it only in tests that verify an assertion helper, or in tools that report failures. - Test runner behavior.
node:testtreats any thrown error as a failed test and printsAssertionErrordetails, includingactual,expectedand the location, in the report. - Stack traces. Without
stackStartFn, the trace includes the assertion library frames. Built-in assertions pass the right function for you.