assert

What is assert?

The assert npm package is a module that provides a set of assertion functions for verifying invariants. It is primarily used for writing tests to ensure that code behaves as expected. The module includes functions to test strict equality, deep equality, and various other conditions.

What are assert's main functionalities?

Strict Equality Assertion

This feature is used to test if two values are strictly equal using the === operator.

const assert = require('assert');
assert.strictEqual(1, 1, '1 is strictly equal to 1');

Deep Equality Assertion

This feature is used to test if two objects or arrays are equal by comparing their properties or elements.

const assert = require('assert');
assert.deepStrictEqual({ a: 1 }, { a: 1 }, 'Objects are deeply equal');

Assertion with a Predicate Function

This feature is used to test if a value passes a specified predicate function.

const assert = require('assert');
assert.ok(value => value > 10, 'Value is greater than 10');

Throws Assertion

This feature is used to test if a function throws an error as expected.

const assert = require('assert');
assert.throws(
  () => { throw new Error('Wrong value'); },
  Error,
  'Function should throw an Error'
);

Other packages similar to assert

chai

Chai is a BDD/TDD assertion library for node and the browser that can be delightfully paired with any javascript testing framework. It offers more plugins and a more flexible API compared to assert.

expect

Expect is a minimalistic assertion library that provides a set of assertion functions and is often used with Jest. It offers a more fluent and readable syntax compared to assert.

should

Should.js is an expressive, readable, framework-agnostic assertion library. It extends the Object prototype with a single non-enumerable getter that allows for a more fluent and chainable API, providing a different style of coding compared to assert.

README

assert

This module is used for writing unit tests for your applications, you can access it with require('assert').

It aims to be fully compatibe with the node.js assert module, same API and same behavior, just adding support for web browsers. The API and code may contain traces of the CommonJS Unit Testing 1.0 spec which they were based on, but both have evolved significantly since then.

A strict and a legacy mode exist, while it is recommended to only use strict mode.

Strict mode

When using the strict mode, any assert function will use the equality used in the strict function mode. So assert.deepEqual() will, for example, work the same as assert.deepStrictEqual().

It can be accessed using:

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

Legacy mode

Deprecated: Use strict mode instead.

When accessing assert directly instead of using the strict property, the Abstract Equality Comparison will be used for any function without a "strict" in its name (e.g. assert.deepEqual()).

It can be accessed using:

const assert = require('assert');

It is recommended to use the strict mode instead as the Abstract Equality Comparison can often have surprising results. Especially in case of assert.deepEqual() as the used comparison rules there are very lax.

E.g.

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

assert.fail(actual, expected, message, operator)

Throws an exception that displays the values for actual and expected separated by the provided operator.

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

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

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

Tests shallow, coercive equality with the equal comparison operator ( == ).

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

Tests shallow, coercive non-equality with the not equal comparison operator ( != ).

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

Tests for deep equality.

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

Tests for deep equality, as determined by the strict equality operator ( === )

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

Tests for any deep inequality.

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

Tests strict equality, as determined by the strict equality operator ( === )

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

Tests strict non-equality, as determined by the strict not equal operator ( !== )

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

Expects block to throw an error. error can be constructor, regexp or validation function.

Validate instanceof using constructor:

assert.throws(function() { throw new Error("Wrong value"); }, Error);

Validate error message using RegExp:

assert.throws(function() { throw new Error("Wrong value"); }, /value/);

Custom error validation:

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

assert.doesNotThrow(block, [message])

Expects block not to throw an error, see assert.throws for details.

assert.ifError(value)

Tests if value is not a false value, throws if it is a true value. Useful when testing the first argument, error in callbacks.

Changelog

1.5.1

• [Deps] switch to object.assign, and unpin util