Assert | Node.js v13.0.0 Documentation

Node.js

- About these Docs
- Usage & Example

- Assertion Testing
- Async Hooks
- Buffer
- C++ Addons
- C/C++ Addons - N-API
- Child Processes
- Cluster
- Command Line Options
- Console
- Crypto
- Debugger
- Deprecated APIs
- DNS
- Domain
- ECMAScript Modules
- Errors
- Events
- File System
- Globals
- HTTP
- HTTP/2
- HTTPS
- Inspector
- Internationalization
- Modules
- Net
- OS
- Path
- Performance Hooks
- Policies
- Process
- Punycode
- Query Strings
- Readline
- REPL
- Report
- Stream
- String Decoder
- Timers
- TLS/SSL
- Trace Events
- TTY
- UDP/Datagram
- URL
- Utilities
- V8
- VM
- Worker Threads
- Zlib

- GitHub Repo & Issue Tracker

# Assert#

Stability: 2 - Stable

The `assert` module provides a set of assertion functions for verifying invariants. The module provides a recommended `strict` mode and a more lenient legacy mode.

## 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)#

Added in: v0.1.21

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

## Strict mode#

History

Version | Changes
--- | ---
v9.9.0 | Added error diffs to the strict mode
v9.9.0 | Added strict mode to the assert module.
v9.9.0 | Added in: v9.9.0

In `strict` mode, `assert` functions use the comparison in the corresponding strict functions. For example, `assert.deepEqual()` will behave like `assert.deepStrictEqual()`.

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

To use `strict` 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 `NODE_DISABLE_COLORS` environment variable. This will also deactivate the colors in the REPL.

## Legacy mode#

Legacy mode uses the Abstract Equality Comparison in:

- `assert.deepEqual()`
- `assert.equal()`
- `assert.notDeepEqual()`
- `assert.notEqual()`

To use legacy mode:

    const assert = require('assert');

Whenever possible, use the `strict` 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());

## assert(value[, message])[src]#

Added in: v0.5.9

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

An alias of `assert.ok()`.

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

History

Version | Changes
--- | ---
v12.0.0 | The type tags are now properly compared and there are a couple minor comparison adjustments to make the check less surprising.
v9.0.0 | The `Error` names and messages are now properly compared
v8.0.0 | The `Set` and `Map` content is also compared
v6.4.0, v4.7.1 | Typed array slices are handled correctly now.
v6.1.0, v4.5.0 | Objects with circular references can be used as inputs now.
v5.10.1, v4.4.3 | Handle non-`Uint8Array` typed arrays correctly.
v0.1.21 | Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Strict mode

An alias of `assert.deepStrictEqual()`.

Legacy mode

Stability: 0 - Deprecated: Use `assert.deepStrictEqual()` instead.

Tests for deep equality between the `actual` and `expected` parameters. Consider using `assert.deepStrictEqual()` instead. `assert.deepEqual()` can have potentially 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])[src]#

History

Version | Changes
--- | ---
v9.0.0 | Enumerable symbol properties are now compared.
v9.0.0 | The `NaN` is now compared using the SameValueZero comparison.
v8.5.0 | The `Error` names and messages are now properly compared
v8.0.0 | The `Set` and `Map` content is also compared
v6.4.0, v4.7.1 | Typed array slices are handled correctly now.
v6.1.0 | Objects with circular references can be used as inputs now.
v5.10.1, v4.4.3 | Handle non-`Uint8Array` typed arrays correctly.
v1.2.0 | Added in: v1.2.0

- `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.doesNotReject(asyncFn[, error][, message])[src]#

Added in: v10.0.0

- `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])[src]#

History

Version | Changes
--- | ---
v5.11.0, v4.4.5 | The `message` parameter is respected now.
v4.2.0 | The `error` parameter can now be an arrow function.
v0.1.21 | Added in: v0.1.21

- `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 `TypeError` because there is no matching error type in the assertion:

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

However, the following will result in an `AssertionError` with the message 'Got unwanted exception...':

    assert.doesNotThrow(
      () => {
        throw new TypeError('Wrong value');
      },
      TypeError
    );

If an `AssertionError` is thrown and a value is provided for the `message` parameter, the value of `message` will be appended to the `AssertionError` message:

    assert.doesNotThrow(
      () => {
        throw new TypeError('Wrong value');
      },
      /Wrong value/,
      'Whoops'
    );
    // Throws: AssertionError: Got unwanted exception: Whoops

## assert.equal(actual, expected[, message])[src]#

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Strict mode

An alias of `assert.strictEqual()`.

Legacy mode

Stability: 0 - Deprecated: Use `assert.strictEqual()` instead.

Tests shallow, coercive equality between the `actual` and `expected` parameters using the Abstract Equality Comparison ( `==` ).

    const assert = require('assert');

    assert.equal(1, 1);
    // OK, 1 == 1
    assert.equal(1, '1');
    // OK, 1 == '1'

    assert.equal(1, 2);
    // AssertionError: 1 == 2
    assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
    // AssertionError: { a: { b: 1 } } == { a: { b: 1 } }

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.fail([message])[src]#

Added in: v0.1.21

- `message` <string> | <Error> Default: `'Failed'`

Throws an `AssertionError` with the provided error message or a default error message. If the `message` parameter is an instance of an `Error` then it will be thrown instead of the `AssertionError`.

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

    assert.fail();
    // AssertionError [ERR_ASSERTION]: Failed

    assert.fail('boom');
    // AssertionError [ERR_ASSERTION]: boom

    assert.fail(new TypeError('need array'));
    // TypeError: need array

Using `assert.fail()` with more than two arguments is possible but deprecated. See below for further details.

## assert.fail(actual, expected[, message[, operator[, stackStartFn]]])[src]#

History

Version | Changes
--- | ---
v10.0.0 | Calling `assert.fail()` with more than one argument is deprecated and emits a warning.
v0.1.21 | Added in: v0.1.21

Stability: 0 - Deprecated: Use `assert.fail([message])` or other assert functions instead.

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>
- `operator` <string> Default: `'!='`
- `stackStartFn` <Function> Default: `assert.fail`

If `message` is falsy, the error message is set as the values of `actual` and `expected` separated by the provided `operator`. If just the two `actual` and `expected` arguments are provided, `operator` will default to `'!='`. If `message` is provided as third argument it will be used as the error message and the other arguments will be stored as properties on the thrown object. If `stackStartFn` is provided, all stack frames above that function will be removed from stacktrace (see `Error.captureStackTrace`). If no arguments are given, the default message `Failed` will be used.

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

    assert.fail('a', 'b');
    // AssertionError [ERR_ASSERTION]: 'a' != 'b'

    assert.fail(1, 2, undefined, '>');
    // AssertionError [ERR_ASSERTION]: 1 > 2

    assert.fail(1, 2, 'fail');
    // AssertionError [ERR_ASSERTION]: fail

    assert.fail(1, 2, 'whoops', '>');
    // AssertionError [ERR_ASSERTION]: whoops

    assert.fail(1, 2, new TypeError('need array'));
    // TypeError: need array

In the last three cases `actual`, `expected`, and `operator` have no influence on the error message.

Example use of `stackStartFn` for truncating the exception's stacktrace:

    function suppressFrame() {
      assert.fail('a', 'b', undefined, '!==', suppressFrame);
    }
    suppressFrame();
    // AssertionError [ERR_ASSERTION]: 'a' !== 'b'
    //     at repl:1:1
    //     at ContextifyScript.Script.runInThisContext (vm.js:44:33)
    //     ...

## assert.ifError(value)[src]#

History

Version | Changes
--- | ---
v10.0.0 | Instead of throwing the original error it is now wrapped into an [`AssertionError`][] that contains the full stack trace.
v10.0.0 | Value may now only be `undefined` or `null`. Before all falsy values were handled the same as `null` and did not throw.
v0.1.97 | Added in: v0.1.97

- `value` <any>

Throws `value` if `value` is not `undefined` or `null`. This is useful when testing the `error` argument in callbacks. The stack trace contains all frames from the error passed to `ifError()` including the potential new frames for `ifError()` itself.

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

    assert.ifError(null);
    // OK
    assert.ifError(0);
    // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
    assert.ifError('error');
    // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
    assert.ifError(new Error());
    // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error

    // Create some random error frames.
    let err;
    (function errorFrame() {
      err = new Error('test error');
    })();

    (function ifErrorFrame() {
      assert.ifError(err);
    })();
    // AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
    //     at ifErrorFrame
    //     at errorFrame

## assert.notDeepEqual(actual, expected[, message])[src]#

History

Version | Changes
--- | ---
v9.0.0 | The `Error` names and messages are now properly compared
v8.0.0 | The `Set` and `Map` content is also compared
v6.4.0, v4.7.1 | Typed array slices are handled correctly now.
v6.1.0, v4.5.0 | Objects with circular references can be used as inputs now.
v5.10.1, v4.4.3 | Handle non-`Uint8Array` typed arrays correctly.
v0.1.21 | Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Strict mode

An alias of `assert.notDeepStrictEqual()`.

Legacy mode

Stability: 0 - Deprecated: Use `assert.notDeepStrictEqual()` instead.

Tests for any deep inequality. Opposite of `assert.deepEqual()`.

    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.notDeepEqual(obj1, obj1);
    // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

    assert.notDeepEqual(obj1, obj2);
    // OK

    assert.notDeepEqual(obj1, obj3);
    // AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

    assert.notDeepEqual(obj1, obj4);
    // OK

If the values are deeply 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.notDeepStrictEqual(actual, expected[, message])[src]#

History

Version | Changes
--- | ---
v9.0.0 | The `-0` and `+0` are not considered equal anymore.
v9.0.0 | The `NaN` is now compared using the SameValueZero comparison.
v9.0.0 | The `Error` names and messages are now properly compared
v8.0.0 | The `Set` and `Map` content is also compared
v6.4.0, v4.7.1 | Typed array slices are handled correctly now.
v6.1.0 | Objects with circular references can be used as inputs now.
v5.10.1, v4.4.3 | Handle non-`Uint8Array` typed arrays correctly.
v1.2.0 | Added in: v1.2.0

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Tests for deep strict inequality. Opposite of `assert.deepStrictEqual()`.

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

    assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
    // OK

If the values are deeply and strictly 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.notEqual(actual, expected[, message])[src]#

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Strict mode

An alias of `assert.notStrictEqual()`.

Legacy mode

Stability: 0 - Deprecated: Use `assert.notStrictEqual()` instead.

Tests shallow, coercive inequality with the Abstract Equality Comparison ( `!=` ).

    const assert = require('assert');

    assert.notEqual(1, 2);
    // OK

    assert.notEqual(1, 1);
    // AssertionError: 1 != 1

    assert.notEqual(1, '1');
    // AssertionError: 1 != '1'

If the values are 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.notStrictEqual(actual, expected[, message])[src]#

History

Version | Changes
--- | ---
v10.0.0 | Used comparison changed from Strict Equality to `Object.is()`
v0.1.21 | Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Tests strict inequality between the `actual` and `expected` parameters as determined by the SameValue Comparison.

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

    assert.notStrictEqual(1, 2);
    // OK

    assert.notStrictEqual(1, 1);
    // AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
    //
    // 1

    assert.notStrictEqual(1, '1');
    // OK

If the values are strictly 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.ok(value[, message])[src]#

History

Version | Changes
--- | ---
v10.0.0 | The `assert.ok()` (no arguments) will now use a predefined error message.
v0.1.21 | Added in: v0.1.21

- `value` <any>
- `message` <string> | <Error>

Tests if `value` is truthy. It is equivalent to `assert.equal(!!value, true, message)`.

If `value` is not truthy, 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`. If no arguments are passed in at all `message` will be set to the string: `'No value argument passed to `assert.ok()`'`.

Be aware that in the `repl` the error message will be different to the one thrown in a file! See below for further details.

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

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

    assert.ok();
    // AssertionError: No value argument passed to `assert.ok()`

    assert.ok(false, 'it\'s false');
    // AssertionError: it's false

    // In the repl:
    assert.ok(typeof 123 === 'string');
    // AssertionError: false == true

    // In a file (e.g. test.js):
    assert.ok(typeof 123 === 'string');
    // AssertionError: The expression evaluated to a falsy value:
    //
    //   assert.ok(typeof 123 === 'string')

    assert.ok(false);
    // AssertionError: The expression evaluated to a falsy value:
    //
    //   assert.ok(false)

    assert.ok(0);
    // AssertionError: The expression evaluated to a falsy value:
    //
    //   assert.ok(0)

    // Using `assert()` works the same:
    assert(0);
    // AssertionError: The expression evaluated to a falsy value:
    //
    //   assert(0)

## assert.rejects(asyncFn[, error][, message])[src]#

Added in: v10.0.0

- `asyncFn` <Function> | <Promise>
- `error` <RegExp> | <Function> | <Object> | <Error>
- `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 rejected.

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

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

If specified, `error` can be a `Class`, `RegExp`, a validation function, an object where each property will be tested for, or an instance of error where each property will be tested for including the non-enumerable `message` and `name` properties.

If specified, `message` will be the message provided by the `AssertionError` if the `asyncFn` fails to reject.

    (async () => {
      await assert.rejects(
        async () => {
          throw new TypeError('Wrong value');
        },
        {
          name: 'TypeError',
          message: 'Wrong value'
        }
      );
    })();

    assert.rejects(
      Promise.reject(new Error('Wrong value')),
      Error
    ).then(() => {
      // ...
    });

`error` cannot be a string. If a string is provided as the second argument, then `error` is assumed to be omitted and the string will be used for `message` instead. This can lead to easy-to-miss mistakes. Please read the example in `assert.throws()` carefully if using a string as the second argument gets considered.

## assert.strictEqual(actual, expected[, message])[src]#

History

Version | Changes
--- | ---
v10.0.0 | Used comparison changed from Strict Equality to `Object.is()`
v0.1.21 | Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <string> | <Error>

Tests strict equality between the `actual` and `expected` parameters as determined by the SameValue Comparison.

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

    assert.strictEqual(1, 2);
    // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
    //
    // 1 !== 2

    assert.strictEqual(1, 1);
    // OK

    assert.strictEqual('Hello foobar', 'Hello World!');
    // AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
    // + actual - expected
    //
    // + 'Hello foobar'
    // - 'Hello World!'
    //          ^

    const apples = 1;
    const oranges = 2;
    assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
    // AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

    assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
    // TypeError: Inputs are not identical

If the values are not strictly 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.throws(fn[, error][, message])[src]#

History

Version | Changes
--- | ---
v10.2.0 | The `error` parameter can be an object containing regular expressions now.
v9.9.0 | The `error` parameter can now be an object as well.
v4.2.0 | The `error` parameter can now be an arrow function.
v0.1.21 | Added in: v0.1.21

- `fn` <Function>
- `error` <RegExp> | <Function> | <Object> | <Error>
- `message` <string>

Expects the function `fn` to throw an error.

If specified, `error` can be a `Class`, `RegExp`, a validation function, a validation object where each property will be tested for strict deep equality, or an instance of error where each property will be tested for strict deep equality including the non-enumerable `message` and `name` properties. When using an object, it is also possible to use a regular expression, when validating against a string property. See below for examples.

If specified, `message` will be appended to the message provided by the `AssertionError` if the `fn` call fails to throw or in case the error validation fails.

Custom validation object/error instance:

    const err = new TypeError('Wrong value');
    err.code = 404;
    err.foo = 'bar';
    err.info = {
      nested: true,
      baz: 'text'
    };
    err.reg = /abc/i;

    assert.throws(
      () => {
        throw err;
      },
      {
        name: 'TypeError',
        message: 'Wrong value',
        info: {
          nested: true,
          baz: 'text'
        }
        // Only properties on the validation object will be tested for.
        // Using nested objects requires all properties to be present. Otherwise
        // the validation is going to fail.
      }
    );

    // Using regular expressions to validate error properties:
    assert.throws(
      () => {
        throw err;
      },
      {
        // The `name` and `message` properties are strings and using regular
        // expressions on those will match against the string. If they fail, an
        // error is thrown.
        name: /^TypeError$/,
        message: /Wrong/,
        foo: 'bar',
        info: {
          nested: true,
          // It is not possible to use regular expressions for nested properties!
          baz: 'text'
        },
        // The `reg` property contains a regular expression and only if the
        // validation object contains an identical regular expression, it is going
        // to pass.
        reg: /abc/i
      }
    );

    // Fails due to the different `message` and `name` properties:
    assert.throws(
      () => {
        const otherErr = new Error('Not found');
        // Copy all enumerable properties from `err` to `otherErr`.
        for (const [key, value] of Object.entries(err)) {
          otherErr[key] = value;
        }
        throw otherErr;
      },
      // The error's `message` and `name` properties will also be checked when using
      // an error as validation object.
      err
    );

Validate instanceof using constructor:

    assert.throws(
      () => {
        throw new Error('Wrong value');
      },
      Error
    );

Validate error message using `RegExp`:

Using a regular expression runs `.toString` on the error object, and will therefore also include the error name.

    assert.throws(
      () => {
        throw new Error('Wrong value');
      },
      /^Error: Wrong value$/
    );

Custom error validation:

The function must return `true` to indicate all internal validations passed. It will otherwise fail with an `AssertionError`.

    assert.throws(
      () => {
        throw new Error('Wrong value');
      },
      (err) => {
        assert(err instanceof Error);
        assert(/value/.test(err));
        // Returning anything from validation functions besides `true` is not
        // recommended. By doing that, it's not clear what part of the validation
        // failed. Instead, throw an error about the specific validation that failed
        // (as done in this example) and add as much helpful debugging information
        // to that error as possible.
        return true;
      },
      'unexpected error'
    );

`error` cannot be a string. If a string is provided as the second argument, then `error` is assumed to be omitted and the string will be used for `message` instead. This can lead to easy-to-miss mistakes. Using the same message as the thrown error message is going to result in an `ERR_AMBIGUOUS_ARGUMENT` error. Please read the example below carefully if using a string as the second argument gets considered:

    function throwingFirst() {
      throw new Error('First');
    }
    function throwingSecond() {
      throw new Error('Second');
    }
    function notThrowing() {}

    // The second argument is a string and the input function threw an Error.
    // The first case will not throw as it does not match for the error message
    // thrown by the input function!
    assert.throws(throwingFirst, 'Second');
    // In the next example the message has no benefit over the message from the
    // error and since it is not clear if the user intended to actually match
    // against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.
    assert.throws(throwingSecond, 'Second');
    // TypeError [ERR_AMBIGUOUS_ARGUMENT]

    // The string is only used (as message) in case the function does not throw:
    assert.throws(notThrowing, 'Second');
    // AssertionError [ERR_ASSERTION]: Missing expected exception: Second

    // If it was intended to match for the error message do this instead:
    // It does not throw because the error messages match.
    assert.throws(throwingSecond, /Second$/);

    // If the error message does not match, an AssertionError is thrown.
    assert.throws(throwingFirst, /Second$/);
    // AssertionError [ERR_ASSERTION]

Due to the confusing notation, it is recommended not to use a string as the second argument. This might lead to difficult-to-spot errors.