Table of Contents

• Assert
  • Strict assertion mode
  • Legacy assertion mode
  • Class: assert.AssertionError
    • new assert.AssertionError(options)
  • Class: assert.CallTracker
    • tracker.calls([fn][, exact])
    • tracker.report()
    • tracker.verify()
  • 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#

Source Code: lib/assert.js

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);
}

Class: assert.CallTracker#

This feature is currently experimental and behavior might still change.

### new assert.CallTracker()

Creates a new CallTracker object which can be used to track if functions were called a specific number of times. The tracker.verify() must be called for the verification to take place. The usual pattern would be to call it in a process.on('exit') handler.

const assert = require('assert');

const tracker = new assert.CallTracker();

function func() {}

// callsfunc() must be called exactly 1 time before tracker.verify().
const callsfunc = tracker.calls(func, 1);

callsfunc();

// Calls tracker.verify() and verifies if all tracker.calls() functions have
// been called exact times.
process.on('exit', () => {
  tracker.verify();
});

tracker.calls([fn][, exact])#

• fn <Function> Default A no-op function.
• exact <number> Default 1.
• Returns: <Function> that wraps fn.

The wrapper function is expected to be called exactly exact times. If the function has not been called exactly exact times when tracker.verify() is called, then tracker.verify() will throw an error.

const assert = require('assert');

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func);

tracker.report()#

• Returns: <Array> of objects containing information about the wrapper functions returned by tracker.calls().
• Object <Object>
  • message <string>
  • actual <number> The actual number of times the function was called.
  • expected <number> The number of times the function was expected to be called.
  • operator <string> The name of the function that is wrapped.
  • stack <Object> A stack trace of the function.

The arrays contains information about the expected and actual number of calls of the functions that have not been called the expected number of times.

const assert = require('assert');

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

function foo() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func, 2);

// Returns an array containing information on callsfunc()
tracker.report();
// [
//  {
//    message: 'Expected the func function to be executed 2 time(s) but was
//    executed 0 time(s).',
//    actual: 0,
//    expected: 2,
//    operator: 'func',
//    stack: stack trace
//  }
// ]

tracker.verify()#

Iterates through the list of functions passed to tracker.calls() and will throw an error for functions that have not been called the expected number of times.

const assert = require('assert');

// Creates call tracker.
const tracker = new assert.CallTracker();

function func() {}

// Returns a function that wraps func() that must be called exact times
// before tracker.verify().
const callsfunc = tracker.calls(func, 2);

callsfunc();

// Will throw an error since callsfunc() was only called once.
tracker.verify();

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