Skip to content
Tutorials Center
My learning

Topics

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.

NODE
import assert from 'node:assert';

try {
  assert.strictEqual(1, 2);
} catch (error) {
  console.log(error instanceof assert.AssertionError);
}

Try it

Node.js Inspecting a failed assertion

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.

Node.js A diff and a custom assertion helper

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

NODE
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.AssertionError and error.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 message and generatedMessage: false. Passing an Error instance throws that error unchanged, so it is not an AssertionError.
  • assert.fail(). Called with no arguments, the message is Failed. Its operator is 'fail'.
  • Large objects. The message includes an indented diff. Long unchanged stretches are collapsed so the changes stay visible. Printing error.actual and error.expected yourself gives you the raw values.
  • Do not catch it to hide failures. Catching an AssertionError in 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:test treats any thrown error as a failed test and prints AssertionError details, including actual, expected and 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.