Node.js Assert Module Guide

The assert module provides assertion functions for testing. Here's how to use it effectively.

Basic Assertions#

const assert = require('assert');

// Basic equality
assert.equal(1, 1);          // Passes (loose equality)
assert.equal(1, '1');        // Passes (loose equality)
assert.strictEqual(1, 1);    // Passes (strict equality)
// assert.strictEqual(1, '1'); // Throws!

// Not equal
assert.notEqual(1, 2);       // Passes
assert.notStrictEqual(1, '1'); // Passes

// Truthy/Falsy
assert.ok(true);             // Passes
assert.ok(1);                // Passes
assert.ok('string');         // Passes
// assert.ok(false);         // Throws!
// assert.ok(0);             // Throws!

// Direct assertions
assert(true);                // Same as assert.ok()
assert(1 === 1);

Strict Mode#

const assert = require('assert').strict;
// Or: const assert = require('assert/strict');

// In strict mode, equal uses strict equality
assert.equal(1, 1);   // Passes
// assert.equal(1, '1'); // Throws in strict mode!

// Deep equality is also strict
assert.deepEqual({ a: 1 }, { a: 1 });   // Passes
// assert.deepEqual({ a: 1 }, { a: '1' }); // Throws!

// Recommended: always use strict mode
const { strict: assert } = require('assert');

Deep Equality#

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

// Deep object comparison
assert.deepStrictEqual(
  { a: 1, b: { c: 2 } },
  { a: 1, b: { c: 2 } }
); // Passes

assert.deepStrictEqual(
  [1, 2, [3, 4]],
  [1, 2, [3, 4]]
); // Passes

// Not deep equal
assert.notDeepStrictEqual(
  { a: 1 },
  { a: 2 }
); // Passes

// Works with various types
assert.deepStrictEqual(
  new Date('2021-01-01'),
  new Date('2021-01-01')
);

assert.deepStrictEqual(
  new Map([['a', 1]]),
  new Map([['a', 1]])
);

assert.deepStrictEqual(
  new Set([1, 2, 3]),
  new Set([1, 2, 3])
);

// Prototype checking
const obj1 = Object.create({ proto: true });
const obj2 = Object.create(null);
// assert.deepStrictEqual(obj1, obj2); // Throws - different prototypes

Error Assertions#

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

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

// With specific error
assert.throws(
  () => { throw new TypeError('Invalid'); },
  TypeError
);

// With error message
assert.throws(
  () => { throw new Error('Specific error'); },
  { message: 'Specific error' }
);

// With regex
assert.throws(
  () => { throw new Error('File not found'); },
  /not found/
);

// With validation function
assert.throws(
  () => { throw new Error('Custom error'); },
  (err) => {
    return err instanceof Error && err.message.includes('Custom');
  }
);

// Does not throw
assert.doesNotThrow(
  () => { return 42; }
);

// Async assertions
async function failingAsync() {
  throw new Error('Async error');
}

await assert.rejects(failingAsync, Error);

await assert.rejects(
  failingAsync,
  { message: 'Async error' }
);

// Does not reject
await assert.doesNotReject(
  async () => { return 42; }
);

Custom Messages#

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

// Add context to failures
assert.equal(result, expected, 'Result should match expected value');

assert.ok(user.isActive, `User ${user.id} should be active`);

assert.strictEqual(
  response.status,
  200,
  `Expected status 200, got ${response.status}`
);

// With Error object
assert.fail(new Error('This test should not reach here'));

// Fail with message
assert.fail('Unreachable code executed');

// AssertionError details
try {
  assert.strictEqual(1, 2, 'Numbers should match');
} catch (err) {
  console.log(err.message);  // 'Numbers should match'
  console.log(err.actual);   // 1
  console.log(err.expected); // 2
  console.log(err.operator); // 'strictEqual'
}

Match and ifError#

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

// Match - check if string matches regex
assert.match('hello world', /world/);
assert.match('test@example.com', /^\S+@\S+\.\S+$/);

// Does not match
assert.doesNotMatch('hello', /world/);

// ifError - throws if value is truthy (for callbacks)
assert.ifError(null);     // Passes
assert.ifError(undefined); // Passes
// assert.ifError(new Error('fail')); // Throws the error

// Common callback pattern
function callback(err, result) {
  assert.ifError(err); // Throws if error exists
  assert.ok(result);
}

Testing Patterns#

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

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

// Basic test
function testAdd() {
  assert.strictEqual(add(1, 2), 3);
  assert.strictEqual(add(-1, 1), 0);
  assert.strictEqual(add(0, 0), 0);
  console.log('✓ add tests passed');
}

// Test with setup/teardown
function testDatabase() {
  // Setup
  const db = new Database();
  db.connect();

  try {
    // Test
    const user = db.createUser({ name: 'Alice' });
    assert.ok(user.id);
    assert.strictEqual(user.name, 'Alice');

    const found = db.findUser(user.id);
    assert.deepStrictEqual(found, user);

    console.log('✓ database tests passed');
  } finally {
    // Teardown
    db.disconnect();
  }
}

// Async test
async function testAsyncFunction() {
  const result = await fetchData();
  assert.ok(Array.isArray(result));
  assert.ok(result.length > 0);
  console.log('✓ async tests passed');
}

// Run tests
async function runTests() {
  testAdd();
  testDatabase();
  await testAsyncFunction();
  console.log('All tests passed!');
}

runTests().catch(console.error);

Custom Assertions#

const assert = require('assert').strict;
const { AssertionError } = assert;

// Custom assertion function
function assertInRange(value, min, max, message) {
  if (value < min || value > max) {
    throw new AssertionError({
      message: message || `Expected ${value} to be between ${min} and ${max}`,
      actual: value,
      expected: `${min} - ${max}`,
      operator: 'inRange',
    });
  }
}

// Usage
assertInRange(5, 1, 10);  // Passes
// assertInRange(15, 1, 10); // Throws

// Assert array contains
function assertContains(array, item, message) {
  if (!array.includes(item)) {
    throw new AssertionError({
      message: message || `Expected array to contain ${item}`,
      actual: array,
      expected: item,
      operator: 'contains',
    });
  }
}

// Assert object has property
function assertHasProperty(obj, prop, message) {
  if (!(prop in obj)) {
    throw new AssertionError({
      message: message || `Expected object to have property "${prop}"`,
      actual: Object.keys(obj),
      expected: prop,
      operator: 'hasProperty',
    });
  }
}

// Assert type
function assertType(value, type, message) {
  const actualType = typeof value;
  if (actualType !== type) {
    throw new AssertionError({
      message: message || `Expected type ${type}`,
      actual: actualType,
      expected: type,
      operator: 'typeOf',
    });
  }
}

Integration with Test Runners#

// Works with Node.js test runner (v18+)
const { describe, it } = require('node:test');
const assert = require('assert').strict;

describe('Calculator', () => {
  it('should add numbers', () => {
    assert.strictEqual(add(1, 2), 3);
  });

  it('should subtract numbers', () => {
    assert.strictEqual(subtract(5, 3), 2);
  });

  it('should throw on division by zero', () => {
    assert.throws(
      () => divide(1, 0),
      { message: 'Division by zero' }
    );
  });
});

// With Mocha
describe('User Service', function() {
  it('should create user', async function() {
    const user = await createUser({ name: 'Test' });
    assert.ok(user.id);
    assert.strictEqual(user.name, 'Test');
  });
});

Best Practices#

Usage:
✓ Use strict mode
✓ Provide descriptive messages
✓ Use deepStrictEqual for objects
✓ Test edge cases

Organization:
✓ Group related assertions
✓ Use setup/teardown patterns
✓ Test one thing per test
✓ Name tests descriptively

Error Handling:
✓ Test both success and failure
✓ Use assert.throws for errors
✓ Use assert.rejects for promises
✓ Include error messages

Avoid:
✗ Loose equality (==)
✗ Missing error messages
✗ Testing implementation details
✗ Ignoring async errors

The Node.js assert module provides essential testing primitives. Use strict mode for reliable comparisons, provide clear error messages, and leverage deepStrictEqual for object comparisons. For larger projects, consider using it with a test runner like Node.js's built-in test runner or Mocha.