Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js assert.throws() method

Reference for assert.throws() in Node.js: check that a function throws, and validate the error with a class, regex, object, function or error instance.

assert.throws(fn, [error], [message]) calls fn and passes only if it throws. If fn returns normally, the assertion fails with "Missing expected exception". The optional second argument checks what was thrown, so a test fails when the wrong kind of error appears.

It is for synchronous code. For an async function or a promise use assert.rejects(); calling assert.throws() on an async function would see a returned promise, not a throw.

NODE
import assert from "node:assert/strict";

assert.throws(() => JSON.parse("{bad"), SyntaxError);

Try it

Node.js Five ways to validate the error

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 Missing exceptions and custom messages

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
assert.throws(fn: Function, error?: Function | RegExp | object | Error | ((e: unknown) => boolean), message?: string): void
assert.doesNotThrow(fn: Function, error?: Function | RegExp, message?: string): void
Name Description
fn A function that is expected to throw. It is called with no arguments.
error Optional validation: a class (checked with instanceof), a RegExp (tested against the error's string form), an object (each listed property is compared deeply, and a regex value is matched), a function that returns true for a valid error, or an error instance whose properties must match.
message Optional text used if the assertion fails because nothing was thrown.

Returns: undefined.

Errors: an AssertionError with operator "throws" when nothing is thrown or the error does not match. A TypeError with code ERR_AMBIGUOUS_ARGUMENT is thrown when a string error equals the actual message. A non-function fn throws ERR_INVALID_ARG_TYPE.

Usage notes

  • With an object, only the listed properties are compared. Put name and message there, plus code for system errors.
  • A validation function must return exactly true; any other result fails with a message that includes the caught error.
  • A regex is tested against the error converted to a string, such as TypeError: bad input, so it can match the class name too.
  • When the second argument is a string it is treated as the failure message, not as a matcher.
  • Wrap the call in an arrow function: assert.throws(() => parse(x)). Passing parse(x) runs it before assert sees it and the throw escapes the assertion.
  • assert.doesNotThrow() exists but is rarely useful: if the code throws, the test already fails with a better stack trace.
  • fn can throw anything, including a string, and a regex matcher will still be tested against it.