assert.js

Latest version: 1.1.1

Date: 2025-11-13T19:48:59.826Z

A modern, zero-dependency assertion library for Node.js, Deno and browser (ESM) environments.

Implements and extends the CommonJS Unit Testing 1.0 spec.

Autotest

       

Summary

Category Assertions
Constants assert.VERSION;
Errors assert.AssertionError();
Basic assert();, assert.ok();, assert.notOk();, assert.fail();
Equality assert.equal();, assert.notEqual();, assert.strictEqual();, assert.notStrictEqual();, assert.deepEqual();, assert.notDeepEqual();
Exception assert.throws();, await assert.rejects();, await assert.doesNotReject();
Boolean assert.isTrue();, assert.isFalse();
String assert.match();, assert.doesNotMatch();, assert.stringContains();, assert.stringNotContains();
Comparison assert.lt();, assert.lte();, assert.gt();, assert.gte();, assert.inRange();, assert.notInRange();
Object assert.includes();, assert.doesNotInclude();, assert.isEmpty();, assert.isNotEmpty();
Type assert.is();, assert.isNot();, assert.isPrimitive();, assert.isNotPrimitive();, assert.isNullish();, assert.isNonNullable();, assert.isNull();, assert.isNotNull();, assert.isUndefined();, assert.isDefined();, assert.isString();, assert.isNotString();, assert.isNumber();, assert.isNotNumber();, assert.isBigInt();, assert.isNotBigInt();, assert.isBoolean();, assert.isNotBoolean();, assert.isSymbol();, assert.isNotSymbol();, assert.isFunction();, assert.isNotFunction();, assert.isObject();, assert.isNotObject();, assert.isNaN();, assert.isNotNaN();
Testrunner assert.testSync();, await assert.testAsync();, assert.testCheck();

Tested on these enviroments

Import

Import the assert function

import assert from "./assert.js";
globalThis.assert = assert;

Import the assert function as defaultExport

import defaultExport from "./assert.js";
globalThis.assert = defaultExport;

Dynamic import

const assert = await import("./assert.js");
globalThis.assert = assert;

Constants

assert.VERSION

Added in v1.0.0

Returns the library version string.

console.log(assert.VERSION); // "assert.js v1.1.1"

▲ Back to Summary

Errors

assert.AssertionError([message], [options]);

Added in v1.0.0

Custom error class used internally by all failed assertions.

try {
  assert(false, "example");
} catch (e) {
  if (e instanceof assert.AssertionError) {
    console.log("Caught assertion:", e.message);
  }
}

▲ Back to Summary

Basic Assertions

assert(condition, [message: string | Error]);

Added in v1.0.0

Ensures that condition is truthy. Throws an AssertionError if falsy.

assert(true); // passes
// assert(false, "should be true"); // throws an error fails

▲ Back to Summary

assert.ok(condition, [message: string | Error]);

Added in v1.0.0

Alias for assert(condition, [message: string | Error]);.

assert.ok(1 === 1); // passes
// assert.ok(0, "0 is falsy"); // throws an error

▲ Back to Summary

assert.notOk(condition, [message: string | Error]);

Added in v1.0.0

Ensures a value is falsy.

assert.notOk(0); // passes
assert.notOk(""); // passes
// assert.notOk(true); // throws an error

▲ Back to Summary

assert.fail([message: string | Error]);

Added in v1.0.0

Forces a failure.

// assert.fail("This should fail"); // throws an error

▲ Back to Summary

Equality Assertions

assert.equal(actual, expected, [message: string | Error]);

Added in v1.0.0

Loose equality (==).

assert.equal(1, "1"); // passes
assert.equal(true, 1); // passes
// assert.equal(1, 2); // throws an error

▲ Back to Summary

assert.notEqual(actual, expected, [message: string | Error]);

Added in v1.0.0

Inverse of Equal(actual, expected, [message: string | Error]);.

assert.notEqual(1, 2); // passes
// assert.notEqual(1, "1"); // throws an error

▲ Back to Summary

assert.strictEqual(actual, expected, [message: string | Error]);

Added in v1.0.0

Strict equality (Object.is();).

assert.strictEqual(1, 1); // passes
assert.strictEqual(NaN, NaN); // passes
// assert.strictEqual(1, "1"); // throws an error

▲ Back to Summary

assert.notStrictEqual(actual, expected, [message: string | Error]);

Added in v1.0.0

Inverse of strictEqual(actual, expected, [message: string | Error]);.

assert.notStrictEqual(1, "1"); // passes
// assert.notStrictEqual(NaN, NaN); // throws an error

▲ Back to Summary

assert.deepEqual(actual, expected, [message: string | Error]);

Added in v1.0.0

Deep equality check.

assert.deepEqual({ a: 1 }, { a: 1 }); // passes
assert.deepEqual([1, 2], [1, 2]); // passes
// assert.deepEqual({ a: 1 }, { a: 2 }); // throws an error

▲ Back to Summary

assert.notDeepEqual(actual, expected, [message: string | Error]);

Added in v1.0.0

Inverse of deepEqual(actual, expected, [message: string | Error]);.

assert.notDeepEqual({ a: 1 }, { a: 2 }); // passes
// assert.notDeepEqual({ a: 1 }, { a: 1 }); // throws an error

▲ Back to Summary

Exception Assertions

assert.throws(fn, [ErrorType|string|RegExp], [message: string | Error]);

Added in v1.0.0

Ensures that a function throws.

assert.throws(() => { throw new TypeError("oops"); }, TypeError); // passes
assert.throws(() => { throw new Error("boom"); }, /boom/); // passes
// assert.throws(() => 42); // did not throw

▲ Back to Summary

await assert.rejects(asyncFnOrPromise, [ErrorType|string|RegExp], [message: string | Error]);

Added in v1.0.0

Ensures that an async function or promise rejects.

await assert.rejects(async () => { throw new Error("fail"); }, /fail/);  // passes
// await assert.rejects(async () => 42); // resolved, didn’t reject

▲ Back to Summary

await assert.doesNotReject(asyncFnOrPromise, [ErrorType|string|RegExp], [message: string | Error]);

Added in v1.0.0

Ensures an async function or promise resolves (does not reject).

await assert.doesNotReject(async () => 42); // passes
// await assert.doesNotReject(async () => { throw new Error("oops"); }); // throws an error

▲ Back to Summary

Boolean Assertions

assert.isTrue(value, [message: string | Error]);

Added in v1.0.0

Ensures value is exactly true.

assert.isTrue(true); // passes
// assert.isTrue(1); // throws an error

▲ Back to Summary

assert.isFalse(value, [message: string | Error]);

Added in v1.0.0

Ensures value is exactly false.

assert.isFalse(false); // passes
// assert.isFalse(0); // throws an error

▲ Back to Summary

String Assertions

assert.match(string, regexp, [message: string | Error]);

Added in v1.0.0

Ensures a string matches a regular expression.

assert.match("hello world", /world/); // passes
// assert.match("hello", /bye/); // throws an error

▲ Back to Summary

assert.doesNotMatch(string, regexp, [message: string | Error]);

Added in v1.0.0

Ensures a string does not match a regular expression.

assert.doesNotMatch("hello", /bye/); // passes
// assert.doesNotMatch("hello world", /world/); // throws an error

▲ Back to Summary

assert.stringContains(actual, substring, [message: string | Error]);

Added in v1.0.0

Ensures a string contains a substring.

assert.stringContains("hello world", "world"); // passes
// assert.stringContains("hello", "z"); // throws an error

▲ Back to Summary

assert.stringNotContains(actual, substring, [message: string | Error]);

Added in v1.0.0

Ensures a string does not contain a substring.

assert.stringNotContains("hello", "z"); // passes
// assert.stringNotContains("hello", "he"); // throws an error

▲ Back to Summary

Comparison Assertions

assert.lt(value1, value2, [message: string | Error]);

Added in v1.0.0

Ensures a < b and the value types have to be same type.

assert.lt(3, 5); // passes
// assert.lt(5, 3); // throws an error

▲ Back to Summary

assert.lte(value1, value2, [message: string | Error]);

Added in v1.0.0

Ensures a <= b and the value types have to be same type.

assert.lte(3, 3); // passes
assert.lte(2, 4); // passes
// assert.lte(5, 3); // throws an error

▲ Back to Summary

assert.gt(value1, value2, [message: string | Error]);

Added in v1.0.0

Ensures a > b and the value types have to be same type.

assert.gt(5, 3); // passes
// assert.gt(3, 5); // throws an error

▲ Back to Summary

assert.gte(value1, value2, [message: string | Error]);

Added in v1.0.0

Ensures a >= b and the value types have to be same type.

assert.gte(3, 3); // passes
assert.gte(5, 3); // passes
// assert.gte(2, 3); // throws an error

▲ Back to Summary

assert.inRange(value, min, max, [message: string | Error]);

Added in v1.0.3

Ensures min <= value <= max and the value types have to be same type.

assert.inRange(1, -5, 3); // passes
// assert.inRange(0, 1, 3); // throws an error
// assert.inRange(4, 1, 3); // throws an error
// assert.inRange(2, 1n, 3); // throws an error

▲ Back to Summary

assert.notInRange(value, min, max, [message: string | Error]);

Added in v1.0.3

Inverse of inRange(value, min, max, [message: string | Error]);.

assert.notInRange(0, 1, 3); // passes
assert.notInRange(4, 1, 3); // passes
assert.notInRange(2, 1n, 3); // passes
// assert.notInRange(1, -5, 3); // throws an error

▲ Back to Summary

Object Assertions

assert.includes(container, options: {keyOrValue, [value] }, [message: string | Error]);

Added in v1.0.1

Ensures a container includes a key and value.

Compatible with these types and objects:

assert.includes([1, 2, 3], {keyOrValue: 3 }); // passes
assert.includes({"x": 42}), {keyOrValue: "x"}); // passes
assert.includes({"x": 42}, {keyOrValue: "x", value: 42}); // passes
assert.includes(new Map([["x", 42]]), {keyOrValue: "x"}); // passes
assert.includes(new Map([["x", 42]]), {keyOrValue: "x", value: 42}); // passes
// assert.includes([1, 2, 3], 4); // throws an error
// assert.includes({"x": 42}, {keyOrValue: "y"}); // throws an error
// assert.includes({"x": 42}, {keyOrValue: "x", value: 43}); // throws an error
// assert.includes(new Map([["x", 42]]), {keyOrValue: "y"}); // throws an error
// assert.includes(new Map([["x", 42]]), {keyOrValue: "x", value: 43}); // throws an error

▲ Back to Summary

assert.doesNotInclude(container, options: {keyOrValue, [value] }, [message: string | Error]);

Added in v1.0.1

Inverse of assert.includes(container, options: {keyOrValue, [value] }, [message: string | Error]);.

assert.doesNotInclude([1, 2, 3], 4); // passes
assert.doesNotInclude({"x": 42}, {keyOrValue: "y"}); // passes
assert.doesNotInclude({"x": 42}, {keyOrValue: "x", value: 43}); // passes
assert.doesNotInclude(new Map([["x", 42]]), {keyOrValue: "y"}); // passes
assert.doesNotInclude(new Map([["x", 42]]), {keyOrValue: "x", value: 43}); // passes
// assert.includes([1, 2, 3], {keyOrValue: 3 }); // throws an error
// assert.doesNotInclude({"x": 42}, {keyOrValue: "x"}); // throws an error
// assert.doesNotInclude({"x": 42}, {keyOrValue: "x", value: 42}); // throws an error
// assert.doesNotInclude(new Map([["x", 42]]), {keyOrValue: "x"}); // throws an error
// assert.doesNotInclude(new Map([["x", 42]]), {keyOrValue: "x", value: 42}); // throws an error

▲ Back to Summary

assert.isEmpty(value, [message: string | Error]);

Added in v1.0.1

Ensures value is empty.

assert.isEmpty(new Map()); // passes
// assert.isEmpty([1, 2, 3]); // throws an error

▲ Back to Summary

assert.isNotEmpty(value, [message: string | Error]);

Added in v1.0.1

Inverse of assert.isEmpty(value, [message: string | Error]);.

assert.isNotEmpty([1, 2, 3]); // passes
// assert.isNotEmpty(new Map()); // throws an error

▲ Back to Summary

Type Assertions

assert.is(value, expectedType: string | function | Array<string | function>, [message: string | Error]);

Added in v1.0.0

Ensures a value matches a type or constructor. The expected type can be a string, function or an array of strings and functions.

assert.is(123, "number"); // passes
assert.is([], Array); // passes
assert.is(new Map(), [Map, Object]); // passes
// assert.is("hi", Number); // throws an error

▲ Back to Summary

assert.isNot(value, expectedType: string | function | Array<string | function>, [message: string | Error]);

Added in v1.0.0

Inverse of assert.is(value, expectedType: string | function | Array<string | function>, [message: string | Error]);. The expected type can be a string, function or an array of strings and functions.

assert.isNot("hello", Number); // passes
assert.isNot([], Set); // passes
// assert.isNot([], Array); // throws an error

▲ Back to Summary

assert.isPrimitive(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not object or function.

assert.isPrimitive(42); // passes
// assert.isPrimitive([]]); // throws an error

▲ Back to Summary

assert.isNotPrimitive(value, [message: string | Error]);

Added in v1.0.1

Ensures value is object or function.

assert.isNotPrimitive([]); // passes
// assert.isNotPrimitive(42); // throws an error

▲ Back to Summary

assert.isNullish(value, [message: string | Error]);

Added in v1.0.0

Ensures value is null or undefined.

assert.isNullish(undefined); // passes
assert.isNullish(null); // passes
// assert.isNullish(0); // throws an error

▲ Back to Summary

assert.isNonNullable(value, [message: string | Error]);

Added in v1.0.0

Old name before v1.1.0: assert.isNotNullish();.

Ensures value is not null or undefined.

assert.isNonNullable(42); // passes
assert.isNonNullable("ok"); // passes
// assert.isNonNullable(null); // throws an error

▲ Back to Summary

assert.isNull(value, [message: string | Error]);

Added in v1.0.1

Ensures value is null.

assert.isNull(null); // passes
// assert.isNull(0); // throws an error

▲ Back to Summary

assert.isNotNull(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not null.

assert.isNotNull("ok"); // passes
// assert.isNotNull(null); // throws an error

▲ Back to Summary

assert.isUndefined(value, [message: string | Error]);

Added in v1.0.1

Ensures value is undefined.

assert.isUndefined(undefined); // passes
// assert.isUndefined(0); // throws an error

▲ Back to Summary

assert.isDefined(value, [message: string | Error]);

Added in v1.0.1

Old name before v1.1.0: assert.isNotUndefined();.

Ensures value is not undefined.

assert.isDefined("ok"); // passes
// assert.isDefined(undefined); // throws an error

▲ Back to Summary

assert.isString(value, [message: string | Error]);

Added in v1.0.1

Ensures value is string.

assert.isString("ok"); // passes
// assert.isString(null); // throws an error

▲ Back to Summary

assert.isNotString(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not string.

assert.isNotString(null); // passes
// assert.isNotString("ok"); // throws an error

▲ Back to Summary

assert.isNumber(value, [message: string | Error]);

Added in v1.0.1

Ensures value is number.

assert.isNumber(42); // passes
// assert.isNumber(null); // throws an error

▲ Back to Summary

assert.isNotNumber(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not number.

assert.isNotNumber(null); // passes
// assert.isNotNumber(42); // throws an error

▲ Back to Summary

assert.isBigInt(value, [message: string | Error]);

Added in v1.0.1

Ensures value is bigint.

assert.isBigInt(42n); // passes
// assert.isBigInt(null); // throws an error

▲ Back to Summary

assert.isNotBigInt(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not bigint.

assert.isNotBigInt(null); // passes
// assert.isNotBigInt(42n); // throws an error

▲ Back to Summary

assert.isBoolean(value, [message: string | Error]);

Added in v1.0.1

Ensures value is boolean.

assert.isBoolean(true); // passes
// assert.isBoolean(null); // throws an error

▲ Back to Summary

assert.isNotBoolean(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not boolean.

assert.isNotBoolean(null); // passes
// assert.isNotBoolean(true); // throws an error

▲ Back to Summary

assert.isSymbol(value, [message: string | Error]);

Added in v1.0.1

Ensures value is symbol.

assert.isSymbol(Symbol("foo")); // passes
// assert.isSymbol(null); // throws an error

▲ Back to Summary

assert.isNotSymbol(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not symbol.

assert.isNotSymbol(null); // passes
// assert.isNotSymbol(Symbol("foo")); // throws an error

▲ Back to Summary

assert.isFunction(value, [message: string | Error]);

Added in v1.0.1

Ensures value is function.

assert.isFunction(assert); // passes
// assert.isFunction(null); // throws an error

▲ Back to Summary

assert.isNotFunction(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not function.

assert.isNotFunction(null); // passes
// assert.isNotFunction(assert); // throws an error

▲ Back to Summary

assert.isObject(value, [message: string | Error]);

Added in v1.0.1

Ensures value is object and value is not null.

assert.isObject({a: 1}); // passes
// assert.isObject(null); // throws an error

▲ Back to Summary

assert.isNotObject(value, [message: string | Error]);

Added in v1.0.1

Ensures value is not object or value is null.

assert.isNotObject(null); // passes
// assert.isNotObject({a: 1}); // throws an error

▲ Back to Summary

assert.isNaN(value, [message: string | Error]);

Added in v1.0.2

Ensures value is number and NaN. 
assert.isNaN(0 / 0); // passes
// assert.isNaN(42); // throws an error
// assert.isNaN("foo"); // throws an error

▲ Back to Summary

assert.isNotNaN(value, [message: string | Error]);

Added in v1.0.2

Inverse of assert.isNaN(value, [message: string | Error]);.

assert.isNotObject(42); // passes
assert.isNotObject("foo"); // passes
// assert.isNotObject(0 /0); // throws an error

▲ Back to Summary

Testrunner

assert.testSync(block, name = "assert.testSync"): {ok: true, value: T, block: Function, name: string} | {ok: false, error: Error, block: Function, name: string}

Added in v1.0.0

Synchronously runs a block of code and returns either its result or the caught error.

if (assert.testCheck(assert.testSync(() => 42))) {
  console.log("passed");
} else {
  console.error("failed");
}

▲ Back to Summary

await assert.testAsync(block, name = "assert.testAsync"): {ok: true, value: T, block: Function, name: string} | {ok: false, error: Error, block: Function, name: string}

Added in v1.0.0

Asynchronously runs a block of code and returns either its result or the caught error.

(async () => {
  const result = await assert.testAsync(async function () { return 42; });
  if (assert.testCheck(result)) {
    console.log("passed");
  } else {
    console.error("failed");
  }
})();

▲ Back to Summary

assert.testCheck(result: {ok: true, value: T, block: Function, name: string} | {ok: false, error: Error, block: Function, name: string}): result.ok is true

Added in v1.0.0

Ensures if the result is successful.

if (assert.testCheck(assert.testSync(() => 42))) {
  console.log("passed");
} else {
  console.error("failed");
}

▲ Back to Summary

Example Test File

import assert from "./assert.js"

function add(a, b) {
  return a + b;
}

assert.strictEqual(add(2, 3), 5); // passes
assert.notEqual(add(1, 1), 3); // passes
assert.is(add, Function); // passes
assert.doesNotReject(async () => add(1, 2)); // passes

License

https://opensource.org/licenses/MIT

MIT License

SPDX short identifier: MIT

Copyright (c) 2025 Ferenc Czigler

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

© Copyright 2025 Ferenc Czigler https://github.com/Serrin