Loading lesson path
Concept visual
Start at both ends
The Assert module provides a simple yet powerful set of assertion tests for validating invariants in your code. It's a core Node.js module that doesn't require installation.
While not as feature-rich as testing frameworks like Jest or Mocha, the Assert module is lightweight and perfect for simple testing needs or when you want to avoid external dependencies.
Here's a quick example of using the Assert module to test a simple function:
const assert = require('assert').strict;
// Function to test function add(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
throw new TypeError('Inputs must be numbers');
}
return a + b;
}
// Test cases assert.strictEqual(add(2, 3), 5, '2 + 3 should equal 5');
// Test error case assert.throws(
() => add('2', 3),TypeError,
Formula
'Should throw TypeError for non - number input');
console.log('All tests passed!');There are several ways to import and use the Assert module in your Node.js application: CommonJS Import (Node.js)
// Basic require const assert = require('assert');
// Using strict mode (recommended)
const assert = require('assert').strict;
// Destructuring specific methods const { strictEqual, deepStrictEqual, throws } = require('assert');
// For async/await tests const { rejects, doesNotReject } = require('assert').strict;
ES Modules (Node.js 12+)
// Using default import import assert from 'assert';// Using strict mode with ESM
import { strict as assert } from 'assert';
// Importing specific methods import { strictEqual, deepStrictEqual } from 'assert';
// Dynamic import const { strict: assert } = await import('assert');The strict mode is recommended as it provides more accurate comparisons and better error messages. It's also more aligned with future versions of Node.js where strict mode will be the default.
The Assert module provides several methods for making assertions about values in your code. These methods form the foundation of testing with the Assert module. assert(value[, message]) Tests if a value is truthy. If the value is falsy, an AssertionError is thrown.
const assert = require('assert');
// This will pass assert(true);
assert(1);
assert('string');
assert({});
try {
// This will throw an AssertionError assert(false, 'This value is not truthy');
} catch (err) {
console.error(`Error: ${err.message}`);
}
try {
// These will also throw errors assert(0);
assert('');
assert(null);
assert(undefined);
} catch (err) {
console.error(`Error: ${err.message}`);
}
assert.ok(value[, message])
This is an alias for assert().
const assert = require('assert');
// These assertions are equivalent assert.ok(true, 'This value is truthy');
assert(true, 'This value is truthy');The Assert module provides multiple ways to compare values, each with different behaviors regarding type coercion and object comparison. assert.equal(actual, expected[, message]) Tests shallow, coercive equality between the actual and expected parameters using the equality operator ( == ).
const assert = require('assert');
// These will pass (coercive equality)
assert.equal(1, 1);
assert.equal('1', 1); // String is coerced to number assert.equal(true, 1); // Boolean is coerced to number try {
// This will throw an error assert.equal(1, 2, '1 is not equal to 2');
} catch (err) {
console.error(`Error: ${err.message}`);
}
assert.strictEqual(actual, expected[, message])
Tests strict equality between the actual and expected parameters using the strict equality operator (
===).
const assert = require('assert');
// This will pass assert.strictEqual(1, 1);
try {
// These will throw errors (strict equality)
assert.strictEqual('1', 1, 'String "1" is not strictly equal to number 1');
assert.strictEqual(true, 1, 'true is not strictly equal to 1');
} catch (err) {
console.error(`Error: ${err.message}`);
}over equal() to avoid unexpected type coercion issues.
When working with objects and arrays, you'll need to use deep equality checks to compare their contents rather than just their references. For comparing objects and arrays, Node.js provides deep equality functions: assert.deepEqual(actual, expected[, message]) Tests for deep equality between the actual and expected parameters with loose equality ( == ). assert.deepStrictEqual(actual, expected[, message]) Tests for deep equality between the actual and expected parameters with strict equality ( === ).
const assert = require('assert');
// Objects with the same structure const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { a: 1, b: { c: 2 } };
const obj3 = { a: '1', b: { c: '2' } };
// These will pass assert.deepEqual(obj1, obj2);
assert.deepStrictEqual(obj1, obj2);
// This will pass (loose equality)
assert.deepEqual(obj1, obj3);
try {
// This will throw an error (strict equality)
assert.deepStrictEqual(obj1, obj3, 'Objects are not strictly deep-equal');
} catch (err) {
console.error(`Error: ${err.message}`);
}
// Arrays const arr1 = [1, 2, [3, 4]];
const arr2 = [1, 2, [3, 4]];
const arr3 = ['1', '2', ['3', '4']];
// These will pass assert.deepEqual(arr1, arr2);
assert.deepStrictEqual(arr1, arr2);
// This will pass (loose equality)
assert.deepEqual(arr1, arr3);
try {
// This will throw an error (strict equality)
assert.deepStrictEqual(arr1, arr3, 'Arrays are not strictly deep-equal');
} catch (err) {
console.error(`Error: ${err.message}`);
}Just as important as checking for equality is verifying that values are not equal when they shouldn't be. assert.notEqual(actual, expected[, message]) Tests shallow, coercive inequality using the inequality operator ( != ). assert.notStrictEqual(actual, expected[, message]) Tests strict inequality using the strict inequality operator ( !== ).
const assert = require('assert');
// These will pass assert.notEqual(1, 2);
assert.notStrictEqual('1', 1);
try {
// This will throw an error assert.notEqual(1, '1', '1 is coercively equal to "1"');
} catch (err) {
console.error(`Error: ${err.message}`);
}
try {
// This will throw an error assert.notStrictEqual(1, 1, '1 is strictly equal to 1');
} catch (err) {
console.error(`Error: ${err.message}`);
}
Deep Inequality assert.notDeepEqual(actual, expected[, message])Tests for deep inequality with loose inequality. assert.notDeepStrictEqual(actual, expected[, message]) Tests for deep inequality with strict inequality.
const assert = require('assert');
const obj1 = { a: 1, b: 2 };
const obj2 = { a: 1, b: 3 };
const obj3 = { a: '1', b: '2' };
// These will pass assert.notDeepEqual(obj1, obj2);
assert.notDeepStrictEqual(obj1, obj2);
assert.notDeepStrictEqual(obj1, obj3);
try {
// This will throw an error (loose equality)
assert.notDeepEqual(obj1, obj3, 'obj1 is loosely deep-equal to obj3');
} catch (err) {
console.error(`Error: ${err.message}`);
}Testing that your code throws the expected errors is a critical part of writing robust applications. The Assert module provides several methods for this purpose. assert.throws(fn[, error][, message])
Expects the function fn to throw an error. If not, an AssertionError is thrown.
const assert = require('assert');
// Function that throws an error function throwingFunction() {
throw new Error('Error thrown');
}
// This will pass assert.throws(throwingFunction);
// Check for a specific error message assert.throws(throwingFunction, /Error thrown/, 'Unexpected error message'
);
// Check for a specific error type assert.throws(throwingFunction, Error, 'Wrong error type'
);
// Check with a validation function assert.throws(
throwingFunction, function(err) {
return err instanceof Error && /thrown/.test(err.message);
},
'Error validation failed'
);
try {
// This will throw an AssertionError assert.throws(() => {
// This function doesn't throw return 'no error';
}, 'Expected function to throw');
} catch (err) {
console.error(`Error: ${err.message}`);
}
assert.doesNotThrow(fn[, error][, message])
Expects the function fn to not throw an error. If it does, the error is propagated.
const assert = require('assert');
// This will pass assert.doesNotThrow(() => {
return 'no error';
});
try {
// This will throw the original error assert.doesNotThrow(() => {
throw new Error('This will be thrown');
}, 'Unexpected error');
} catch (err) {
console.error(`Error: ${err.message}`);
}Modern JavaScript makes heavy use of asynchronous patterns.
Formula
The Assert module provides utilities for testing both Promise - based and callback - based asynchronous code.assert.rejects(asyncFn[, error][, message]) Awaits the asyncFn promise or async function and expects it to reject.
const assert = require('assert');
async function asyncTest() {
// Function that returns a rejecting promise function failingAsyncFunction() {
return Promise.reject(new Error('Async error'));
}
// This will pass await assert.rejects(
failingAsyncFunction(),/Async error/
);
// This will also pass await assert.rejects(
async () => {
throw new Error('Async function error');
},
{
name: 'Error', message: 'Async function error'
}
);
try {
// This will throw an AssertionError await assert.rejects(
Promise.resolve('success'),
'Expected promise to reject'
);
} catch (err) {
console.error(`Error: ${err.message}`);
}
}
// Run the async test asyncTest().catch(err => console.error(`Unhandled error: ${err.message}`));
assert.doesNotReject(asyncFn[, error][, message])Awaits the asyncFn promise or async function and expects it to fulfill.
const assert = require('assert');
async function asyncTest() {
// This will pass await assert.doesNotReject(
Promise.resolve('success')
);
// This will also pass await assert.doesNotReject(
async () => {
return 'async function success';
}
);
try {
// This will throw the original rejection reason await assert.doesNotReject(
Promise.reject(new Error('Failure')),
'Expected promise to fulfill'
);
} catch (err) {
console.error(`Error: ${err.message}`);
}
}
// Run the async test asyncTest().catch(err => console.error(`Unhandled error: ${err.message}`));
Other Assertion Methods assert.match(string, regexp[, message])Expects the string input to match the regular expression.
const assert = require('assert');
// This will pass assert.match('I love Node.js', /Node\.js/);
try {
// This will throw an AssertionError assert.match('Hello World', /Node\.js/, 'String does not match the pattern');
} catch (err) {
console.error(`Error: ${err.message}`);
}
assert.fail([message])Throws an AssertionError with the provided message or a default message.
const assert = require('assert');
try {
// This always throws an AssertionError assert.fail('This test always fails');
} catch (err) {
console.error(`Error: ${err.message}`);
}Node.js provides a strict mode for assertions which uses strict equality for all comparisons. It's recommended to use strict mode for more predictable results.
// Import the strict version of assert const assert = require('assert').strict;
// These are equivalent assert.strictEqual(1, 1);
assert.equal(1, 1); // In strict mode, this is the same as strictEqual
// These are equivalent assert.deepStrictEqual({ a: 1 }, { a: 1 });
assert.deepEqual({ a: 1 }, { a: 1 }); // In strict mode, this is the same as deepStrictEqual try {
// This will throw an error in strict mode assert.equal('1', 1);
} catch (err) {
console.error(`Error: ${err.message}`);
}When to Use Node.js Assert vs Testing Frameworks Use Node.js Assert When:
Building internal Node.js modules Use a Testing Framework (Jest, Mocha, etc.) When: