assert

The assert module provides a set of functions for verifying conditions (assertions). If the condition fails, an AssertionError is thrown.

API Surface

Basic

  • assert(value[, message]) — throws if value is falsy.
  • assert.ok(value[, message]) — same as above.

Equality

  • assert.equal(actual, expected[, message]) — loose equality (==).
  • assert.notEqual(actual, expected[, message]) — not equal.
  • assert.strictEqual(actual, expected[, message]) — strict (===).
  • assert.notStrictEqual(actual, expected[, message]) — strict not equal.

Deep

  • assert.deepEqual(actual, expected[, message]) — deep comparison (== rules).
  • assert.notDeepEqual(...)
  • assert.deepStrictEqual(actual, expected[, message]) — deep + strict.
  • assert.notDeepStrictEqual(...)

Exceptions

  • assert.throws(fn[, error]) — expect function to throw.
  • assert.doesNotThrow(fn[, error])
  • assert.rejects(asyncFn[, error]) — expect promise rejection.
  • assert.doesNotReject(asyncFn[, error])

Misc

  • assert.fail([message]) — always throws.
  • assert.ifError(value) — throws if value is truthy (commonly error).

Examples (English only)

const assert = require("assert");

// Basic
assert.ok(true);
assert.ok(1);

// Equality
assert.strictEqual(2 + 2, 4);
assert.notStrictEqual(2 + 2, 5);

// Deep equality
assert.deepStrictEqual({ a: 1 }, { a: 1 });

// Throws
assert.throws(() => {
  throw new Error("fail");
});

// Rejects (async)
(async () => {
  await assert.rejects(Promise.reject(new Error("bad")));
})();

Notes

  • Use strict variants to avoid coercion pitfalls.
  • Deep comparisons are useful for objects/arrays.
  • Wrap async assertions in async functions.
  • Assertion errors include actual, expected, and operator.