Assert | Node.js v8.9.2 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
- Process
- Punycode
- Query Strings
- Readline
- REPL
- Stream
- String Decoder
- Timers
- TLS/SSL
- Tracing
- TTY
- UDP/Datagram
- URL
- Utilities
- V8
- VM
- ZLIB

- GitHub Repo & Issue Tracker
- Mailing List

# Assert#

Stability: 2 - Stable

The `assert` module provides a simple set of assertion tests that can be used to test invariants.

## assert(value[, message])#

Added in: v0.5.9

- `value` <any>
- `message` <any>

An alias of `assert.ok()`.

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

History

Version | Changes
--- | ---
v8.0.0 | 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` <any>

Tests for deep equality between the `actual` and `expected` parameters. Primitive values are compared with the Abstract Equality Comparison ( `==` ).

Only enumerable "own" properties are considered. The `assert.deepEqual()` implementation does not test the `[[Prototype]]` of objects, attached symbols, or non-enumerable properties — for such checks, consider using `assert.deepStrictEqual()` instead. This can lead to some potentially surprising results. For example, the following example does not throw an `AssertionError` because the properties on the `RegExp` object are not enumerable:

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

An exception is made for `Map` and `Set`. Maps and Sets have their contained items compared too, as expected.

"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, object is equal to itself

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

    assert.deepEqual(obj1, obj3);
    // OK, objects are equal

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

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.

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

History

Version | Changes
--- | ---
v8.5.0 | Error names and messages are now properly compared
v8.0.0 | 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` <any>

Generally identical to `assert.deepEqual()` with a few exceptions:

1. Primitive values are compared using the Strict Equality Comparison ( `===` ). Set values and Map keys are compared using the SameValueZero comparison. (Which means they are free of the caveats).
2. `[[Prototype]]` of objects are compared using the Strict Equality Comparison too.
3. Type tags of objects should be the same.
4. Object wrappers are compared both as objects and unwrapped values.

    const assert = require('assert');

    assert.deepEqual({ a: 1 }, { a: '1' });
    // OK, because 1 == '1'

    assert.deepStrictEqual({ a: 1 }, { a: '1' });
    // AssertionError: { a: 1 } deepStrictEqual { a: '1' }
    // because 1 !== '1' using strict equality

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

    Object.setPrototypeOf(fakeDate, Date.prototype);

    assert.deepEqual(object, fakeDate);
    // OK, doesn't check [[Prototype]]
    assert.deepStrictEqual(object, fakeDate);
    // AssertionError: {} deepStrictEqual Date {}
    // Different [[Prototype]]

    assert.deepEqual(date, fakeDate);
    // OK, doesn't check type tags
    assert.deepStrictEqual(date, fakeDate);
    // AssertionError: 2017-03-11T14:25:31.849Z deepStrictEqual Date {}
    // Different type tags

    assert.deepStrictEqual(new Number(1), new Number(2));
    // Fails because the wrapped number is unwrapped and compared as well.
    assert.deepStrictEqual(new String('foo'), Object('foo'));
    // OK because the object and the string are identical when unwrapped.

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.

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

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

- `block` <Function>
- `error` <RegExp> | <Function>
- `message` <any>

Asserts that the function `block` does not throw an error. See `assert.throws()` for more details.

When `assert.doesNotThrow()` is called, it will immediately call the `block` 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.

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 (TypeError)..':

    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');
      },
      TypeError,
      'Whoops'
    );
    // Throws: AssertionError: Got unwanted exception (TypeError). Whoops

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

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <any>

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.

## assert.fail(message)#

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

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <any>
- `operator` <string> Default: '!='
- `stackStartFunction` <function> Default: `assert.fail`

Throws an `AssertionError`. 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 only it will be used as the error message, the other arguments will be stored as properties on the thrown object. If `stackStartFunction` is provided, all stack frames above that function will be removed from stacktrace (see `Error.captureStackTrace`).

    const assert = require('assert');

    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

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

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

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

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

Example use of `stackStartFunction` 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)#

Added in: v0.1.97

- `value` <any>

Throws `value` if `value` is truthy. This is useful when testing the `error` argument in callbacks.

    const assert = require('assert');

    assert.ifError(0);
    // OK
    assert.ifError(1);
    // Throws 1
    assert.ifError('error');
    // Throws 'error'
    assert.ifError(new Error());
    // Throws Error

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

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <any>

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, obj1 and obj2 are not deeply equal

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

    assert.notDeepEqual(obj1, obj4);
    // OK, obj1 and obj4 are not deeply equal

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.

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

Added in: v1.2.0

- `actual` <any>
- `expected` <any>
- `message` <any>

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

    const assert = require('assert');

    assert.notDeepEqual({ a: 1 }, { a: '1' });
    // AssertionError: { a: 1 } notDeepEqual { a: '1' }

    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.

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

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <any>

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.

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

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <any>

Tests strict inequality as determined by the Strict Equality Comparison ( `!==` ).

    const assert = require('assert');

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

    assert.notStrictEqual(1, 1);
    // AssertionError: 1 !== 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.

## assert.ok(value[, message])#

Added in: v0.1.21

- `value` <any>
- `message` <any>

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.

    const assert = require('assert');

    assert.ok(true);
    // OK
    assert.ok(1);
    // OK
    assert.ok(false);
    // throws "AssertionError: false == true"
    assert.ok(0);
    // throws "AssertionError: 0 == true"
    assert.ok(false, 'it\'s false');
    // throws "AssertionError: it's false"

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

Added in: v0.1.21

- `actual` <any>
- `expected` <any>
- `message` <any>

Tests strict equality as determined by the Strict Equality Comparison ( `===` ).

    const assert = require('assert');

    assert.strictEqual(1, 2);
    // AssertionError: 1 === 2

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

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

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.

## assert.throws(block[, error][, message])#

History

Version | Changes
--- | ---
v4.2.0 | The `error` parameter can now be an arrow function.
v0.1.21 | Added in: v0.1.21

- `block` <Function>
- `error` <RegExp> | <Function>
- `message` <any>

Expects the function `block` to throw an error.

If specified, `error` can be a constructor, `RegExp`, or validation function.

If specified, `message` will be the message provided by the `AssertionError` if the block fails to throw.

Validate instanceof using constructor:

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

Validate error message using `RegExp`:

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

Custom error validation:

    assert.throws(
      () => {
        throw new Error('Wrong value');
      },
      function(err) {
        if ((err instanceof Error) && /value/.test(err)) {
          return true;
        }
      },
      'unexpected error'
    );

Note that `error` can not 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:

    // THIS IS A MISTAKE! DO NOT DO THIS!
    assert.throws(myFunction, 'missing foo', 'did not throw with expected message');

    // Do this instead.
    assert.throws(myFunction, /missing foo/, 'did not throw with expected message');

## Caveats#

For the following cases, consider using ES2015 `Object.is()`, which uses the SameValueZero comparison.

    const a = 0;
    const b = -a;
    assert.notStrictEqual(a, b);
    // AssertionError: 0 !== -0
    // Strict Equality Comparison doesn't distinguish between -0 and +0...
    assert(!Object.is(a, b));
    // but Object.is() does!

    const str1 = 'foo';
    const str2 = 'foo';
    assert.strictEqual(str1 / 1, str2 / 1);
    // AssertionError: NaN === NaN
    // Strict Equality Comparison can't be used to check NaN...
    assert(Object.is(str1 / 1, str2 / 1));
    // but Object.is() can!

For more information, see MDN's guide on equality comparisons and sameness.