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.
import assert from "node:assert/strict"; assert.throws(() => JSON.parse("{bad"), SyntaxError);
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
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
nameandmessagethere, pluscodefor 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)). Passingparse(x)runs it beforeassertsees 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.fncan throw anything, including a string, and a regex matcher will still be tested against it.