Table of Contents

• Assert

  • Strict assertion mode
  • Legacy assertion mode

  • Class: assert.AssertionError

    • new assert.AssertionError(options)
  • assert(value[, message])

  • assert.deepEqual(actual, expected[, message])

    • Comparison details

  • assert.deepStrictEqual(actual, expected[, message])

    • Comparison details
  • assert.doesNotMatch(string, regexp[, message])
  • assert.doesNotReject(asyncFn[, error][, message])
  • assert.doesNotThrow(fn[, error][, message])
  • assert.equal(actual, expected[, message])
  • assert.fail([message])
  • assert.fail(actual, expected[, message[, operator[, stackStartFn]]])
  • assert.ifError(value)
  • assert.match(string, regexp[, message])
  • assert.notDeepEqual(actual, expected[, message])
  • assert.notDeepStrictEqual(actual, expected[, message])
  • assert.notEqual(actual, expected[, message])
  • assert.notStrictEqual(actual, expected[, message])
  • assert.ok(value[, message])
  • assert.rejects(asyncFn[, error][, message])
  • assert.strictEqual(actual, expected[, message])
  • assert.throws(fn[, error][, message])

Assert#

The assert module provides a set of assertion functions for verifying invariants.

Strict assertion mode#

In strict assertion mode, non-strict methods behave like their corresponding strict methods. For example, assert.deepEqual() will behave like assert.deepStrictEqual().

In strict assertion mode, error messages for objects display a diff. In legacy assertion mode, error messages for objects display the objects, often truncated.

To use strict assertion mode:

const assert = require('assert').strict;

Example error diff:

const assert = require('assert').strict;

assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected ... Lines skipped
//
//   [
//     [
// ...
//       2,
// +     3
// -     '3'
//     ],
// ...
//     5
//   ]

To deactivate the colors, use the NO_COLOR or NODE_DISABLE_COLORS environment variables. This will also deactivate the colors in the REPL. For more on color support in terminal environments, read the tty getColorDepth() documentation.

Legacy assertion mode#

Legacy assertion mode uses the Abstract Equality Comparison in:

• assert.deepEqual()
• assert.equal()
• assert.notDeepEqual()
• assert.notEqual()

To use legacy assertion mode:

const assert = require('assert');

Whenever possible, use the strict assertion mode instead. Otherwise, the Abstract Equality Comparison may cause surprising results. This is especially true for assert.deepEqual(), where the comparison rules are lax:

// WARNING: This does not throw an AssertionError!
assert.deepEqual(/a/gi, new Date());

Class: assert.AssertionError[src]#

• Extends: <errors.Error>

Indicates the failure of an assertion. All errors thrown by the assert module will be instances of the AssertionError class.

new assert.AssertionError(options)#

• options <Object>

  • message <string> If provided, the error message is set to this value.
  • actual <any> The actual property on the error instance.
  • expected <any> The expected property on the error instance.
  • operator <string> The operator property on the error instance.
  • stackStartFn <Function> If provided, the generated stack trace omits frames before this function.

A subclass of Error that indicates the failure of an assertion.

All instances contain the built-in Error properties (message and name) and:

• actual <any> Set to the actual argument for methods such as assert.strictEqual().
• expected <any> Set to the expected value for methods such as assert.strictEqual().
• generatedMessage <boolean> Indicates if the message was auto-generated (true) or not.
• code <string> Value is always ERR_ASSERTION to show that the error is an assertion error.
• operator <string> Set to the passed in operator value.

const assert = require('assert');

// Generate an AssertionError to compare the error message later:
const { message } = new assert.AssertionError({
  actual: 1,
  expected: 2,
  operator: 'strictEqual'
});

// Verify error output:
try {
  assert.strictEqual(1, 2);
} catch (err) {
  assert(err instanceof assert.AssertionError);
  assert.strictEqual(err.message, message);
  assert.strictEqual(err.name, 'AssertionError');
  assert.strictEqual(err.actual, 1);
  assert.strictEqual(err.expected, 2);
  assert.strictEqual(err.code, 'ERR_ASSERTION');
  assert.strictEqual(err.operator, 'strictEqual');
  assert.strictEqual(err.generatedMessage, true);
}

assert(value[, message])#

• value <any> The input that is checked for being truthy.
• message <string> | <Error>

An alias of assert.ok().

assert.deepEqual(actual, expected[, message])#

• actual <any>
• expected <any>
• message <string> | <Error>

Strict assertion mode

An alias of assert.deepStrictEqual().

Legacy assertion mode

Tests for deep equality between the actual and expected parameters. Consider using assert.deepStrictEqual() instead. assert.deepEqual() can have surprising results.

Deep equality means that the enumerable "own" properties of child objects are also recursively evaluated by the following rules.

Comparison details#

• Primitive values are compared with the Abstract Equality Comparison ( == ).
• Type tags of objects should be the same.
• Only enumerable "own" properties are considered.
• Error names and messages are always compared, even if these are not enumerable properties.
• Object wrappers are compared both as objects and unwrapped values.
• Object properties are compared unordered.
• Map keys and Set items are compared unordered.
• Recursion stops when both sides differ or both sides encounter a circular reference.
• Implementation does not test the [[Prototype]] of objects.
• Symbol properties are not compared.
• WeakMap and WeakSet comparison does not rely on their values.

The following example does not throw an AssertionError because the primitives are considered equal by the Abstract Equality Comparison ( == ).

// WARNING: This does not throw an AssertionError!
assert.deepEqual('+00000000', false);

"Deep" equality means that the enumerable "own" properties of child objects are evaluated also:

const assert = require('assert');

const obj1 = {
  a: {
    b: 1
  }
};
const obj2 = {
  a: {
    b: 2
  }
};
const obj3 = {
  a: {
    b: 1
  }
};
const obj4 = Object.create(obj1);

assert.deepEqual(obj1, obj1);
// OK

// Values of b are different:
assert.deepEqual(obj1, obj2);
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }

assert.deepEqual(obj1, obj3);
// OK

// Prototypes are ignored:
assert.deepEqual(obj1, obj4);
// AssertionError: { a: { b: 1 } } deepEqual {}

If the values are not equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

assert.deepStrictEqual(actual, expected[, message])#

• actual <any>
• expected <any>
• message <string> | <Error>

Tests for deep equality between the actual and expected parameters. "Deep" equality means that the enumerable "own" properties of child objects are recursively evaluated also by the following rules.

Comparison details#

• Primitive values are compared using the SameValue Comparison, used by Object.is().
• Type tags of objects should be the same.
• [[Prototype]] of objects are compared using the Strict Equality Comparison.
• Only enumerable "own" properties are considered.
• Error names and messages are always compared, even if these are not enumerable properties.
• Enumerable own Symbol properties are compared as well.
• Object wrappers are compared both as objects and unwrapped values.
• Object properties are compared unordered.
• Map keys and Set items are compared unordered.
• Recursion stops when both sides differ or both sides encounter a circular reference.
• WeakMap and WeakSet comparison does not rely on their values. See below for further details.

const assert = require('assert').strict;

// This fails because 1 !== '1'.
assert.deepStrictEqual({ a: 1 }, { a: '1' });
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   {
// +   a: 1
// -   a: '1'
//   }

// The following objects don't have own properties
const date = new Date();
const object = {};
const fakeDate = {};
Object.setPrototypeOf(fakeDate, Date.prototype);

// Different [[Prototype]]:
assert.deepStrictEqual(object, fakeDate);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + {}
// - Date {}

// Different type tags:
assert.deepStrictEqual(date, fakeDate);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + 2018-04-26T00:49:08.604Z
// - Date {}

assert.deepStrictEqual(NaN, NaN);
// OK, because of the SameValue comparison

// Different unwrapped numbers:
assert.deepStrictEqual(new Number(1), new Number(2));
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + [Number: 1]
// - [Number: 2]

assert.deepStrictEqual(new String('foo'), Object('foo'));
// OK because the object and the string are identical when unwrapped.

assert.deepStrictEqual(-0, -0);
// OK

// Different zeros using the SameValue Comparison:
assert.deepStrictEqual(0, -0);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
// + 0
// - -0

const symbol1 = Symbol();
const symbol2 = Symbol();
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 });
// OK, because it is the same symbol on both objects.

assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal:
//
// {
//   [Symbol()]: 1
// }

const weakMap1 = new WeakMap();
const weakMap2 = new WeakMap([[{}, {}]]);
const weakMap3 = new WeakMap();
weakMap3.unequal = true;

assert.deepStrictEqual(weakMap1, weakMap2);
// OK, because it is impossible to compare the entries

// Fails because weakMap3 has a property that weakMap1 does not contain:
assert.deepStrictEqual(weakMap1, weakMap3);
// AssertionError: Expected inputs to be strictly deep-equal:
// + actual - expected
//
//   WeakMap {
// +   [items unknown]
// -   [items unknown],
// -   unequal: true
//   }

If the values are not equal, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

assert.doesNotMatch(string, regexp[, message])#

• string <string>
• regexp <RegExp>
• message <string> | <Error>

Expects the string input not to match the regular expression.

This feature is currently experimental and the name might change or it might be completely removed again.

const assert = require('assert').strict;

assert.doesNotMatch('I will fail', /fail/);
// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...

assert.doesNotMatch(123, /pass/);
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.

assert.doesNotMatch('I will pass', /different/);
// OK

If the values do match, or if the string argument is of another type than string, an AssertionError is thrown with a message property set equal to the value of the message parameter. If the message parameter is undefined, a default error message is assigned. If the message parameter is an instance of an Error then it will be thrown instead of the AssertionError.

assert.doesNotReject(asyncFn[, error][, message])#

• asyncFn <Function> | <Promise>
• error <RegExp> | <Function>
• message <string>

Awaits the asyncFn promise or, if asyncFn is a function, immediately calls the function and awaits the returned promise to complete. It will then check that the promise is not rejected.

If asyncFn is a function and it throws an error synchronously, assert.doesNotReject() will return a rejected Promise with that error. If the function does not return a promise, assert.doesNotReject() will return a rejected Promise with an ERR_INVALID_RETURN_VALUE error. In both cases the error handler is skipped.

Using assert.doesNotReject() is actually not useful because there is little benefit in catching a rejection and then rejecting it again. Instead, consider adding a comment next to the specific code path that should not reject and keep error messages as expressive as possible.

If specified, error can be a Class, RegExp or a validation function. See assert.throws() for more details.

Besides the async nature to await the completion behaves identically to assert.doesNotThrow().

(async () => {
  await assert.doesNotReject(
    async () => {
      throw new TypeError('Wrong value');
    },
    SyntaxError
  );
})();

assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
  .then(() => {
    // ...
  });

assert.doesNotThrow(fn[, error][, message])#

• fn <Function>
• error <RegExp> | <Function>
• message <string>

Asserts that the function fn does not throw an error.

Using assert.doesNotThrow() is actually not useful because there is no benefit in catching an error and then rethrowing it. Instead, consider adding a comment next to the specific code path that should not throw and keep error messages as expressive as possible.

When assert.doesNotThrow() is called, it will immediately call the fn function.

If an error is thrown and it is the same type as that specified by the error parameter, then an AssertionError is thrown. If the error is of a different type, or if the error parameter is undefined, the error is propagated back to the caller.

If specified, error can be a Class, RegExp or a validation function. See assert.throws() for more details.

The following, for instance, will throw the