Node.js Assert Module Guide

The assert module provides functions for verifying invariants and writing tests.

Basic Assertions#

import assert from 'assert';

// assert(value) - truthy check
assert(true);           // OK
assert(1);              // OK
assert('hello');        // OK
// assert(false);       // AssertionError
// assert(0);           // AssertionError
// assert('');          // AssertionError

// With custom message
assert(value, 'Value must be truthy');

// assert.ok() - same as assert()
assert.ok(true);
assert.ok(1 > 0, 'One should be greater than zero');

Equality Assertions#

import assert from 'assert';

// Strict equality (===)
assert.strictEqual(1, 1);           // OK
assert.strictEqual('a', 'a');       // OK
// assert.strictEqual(1, '1');      // AssertionError

// Loose equality (==)
assert.equal(1, '1');               // OK (coercion)
assert.equal(null, undefined);      // OK

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

// Deep equality (objects/arrays)
assert.deepStrictEqual(
  { a: 1, b: { c: 2 } },
  { a: 1, b: { c: 2 } }
);  // OK

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

// Deep not equal
assert.notDeepStrictEqual(
  { a: 1 },
  { a: 2 }
);  // OK

Strict vs Legacy Mode#

import assert from 'assert/strict';
// Or: import { strict as assert } from 'assert';

// In strict mode:
// - assert.equal becomes assert.strictEqual
// - assert.deepEqual becomes assert.deepStrictEqual
// - assert.notEqual becomes assert.notStrictEqual

assert.equal(1, 1);   // Uses strictEqual
// assert.equal(1, '1');  // AssertionError in strict mode

// Always prefer strict mode for new code
import { strict as assert } from 'assert';

assert.deepEqual({ a: 1 }, { a: 1 });  // Uses deepStrictEqual

Error Assertions#

import { strict as assert } from 'assert';

// assert.throws - sync function throws
assert.throws(
  () => { throw new Error('Wrong!'); },
  Error
);

// With message matcher
assert.throws(
  () => { throw new Error('Invalid input'); },
  /Invalid/
);

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

// With custom validation
assert.throws(
  () => { throw new TypeError('Type error'); },
  (err) => {
    assert.strictEqual(err.name, 'TypeError');
    assert.strictEqual(err.message, 'Type error');
    return true;  // Must return true
  }
);

// assert.doesNotThrow
assert.doesNotThrow(
  () => { return 42; },
  'Should not throw'
);

Async Assertions#

import { strict as assert } from 'assert';

// assert.rejects - async function rejects
await assert.rejects(
  async () => { throw new Error('Async error'); },
  Error
);

await assert.rejects(
  async () => { throw new Error('Failed'); },
  {
    name: 'Error',
    message: 'Failed'
  }
);

// With promise
await assert.rejects(
  Promise.reject(new Error('Rejected')),
  /Rejected/
);

// assert.doesNotReject
await assert.doesNotReject(
  async () => { return 'success'; }
);

await assert.doesNotReject(
  Promise.resolve('value')
);

Pattern Matching#

import { strict as assert } from 'assert';

// assert.match - regex matching
assert.match('hello world', /world/);
assert.match('test@example.com', /^\S+@\S+\.\S+$/);

// assert.doesNotMatch
assert.doesNotMatch('hello', /world/);
assert.doesNotMatch('abc', /\d+/);

// Object pattern matching
const user = {
  id: 1,
  name: 'John',
  email: 'john@example.com',
  createdAt: new Date()
};

// Partial match with properties
assert.deepStrictEqual(
  { id: user.id, name: user.name },
  { id: 1, name: 'John' }
);

// Custom matcher
function assertMatch(obj, pattern) {
  for (const [key, matcher] of Object.entries(pattern)) {
    if (typeof matcher === 'function') {
      assert.ok(matcher(obj[key]), `${key} failed validation`);
    } else if (matcher instanceof RegExp) {
      assert.match(obj[key], matcher);
    } else {
      assert.strictEqual(obj[key], matcher);
    }
  }
}

assertMatch(user, {
  id: 1,
  name: 'John',
  email: /^.+@.+\..+$/,
  createdAt: d => d instanceof Date
});

Fail Assertions#

import { strict as assert } from 'assert';

// Always fails
// assert.fail();
// assert.fail('Custom error message');
// assert.fail(new Error('Custom error'));

// Conditional fail
function processValue(value) {
  if (typeof value !== 'number') {
    assert.fail('Expected number');
  }
  return value * 2;
}

// Unreachable code
function handleCase(type) {
  switch (type) {
    case 'a':
      return 1;
    case 'b':
      return 2;
    default:
      assert.fail(`Unexpected type: ${type}`);
  }
}

Testing Examples#

import { strict as assert } from 'assert';
import { describe, it } from 'node:test';

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

    it('should handle negative numbers', () => {
      assert.strictEqual(add(-1, 1), 0);
    });

    it('should throw for non-numbers', () => {
      assert.throws(
        () => add('a', 'b'),
        TypeError
      );
    });
  });
});

// Async testing
describe('UserService', () => {
  it('should fetch user by id', async () => {
    const user = await userService.getById(1);

    assert.deepStrictEqual(user, {
      id: 1,
      name: 'John',
      email: 'john@example.com'
    });
  });

  it('should throw for non-existent user', async () => {
    await assert.rejects(
      userService.getById(999),
      { name: 'NotFoundError' }
    );
  });
});

Custom Assertions#

import { strict as assert } from 'assert';

// Create custom assertion functions
function assertIsPositive(value, message) {
  assert.ok(
    typeof value === 'number' && value > 0,
    message || `Expected positive number, got ${value}`
  );
}

function assertArrayIncludes(arr, item, message) {
  assert.ok(
    arr.includes(item),
    message || `Array does not include ${item}`
  );
}

function assertType(value, type, message) {
  const actualType = typeof value;
  assert.strictEqual(
    actualType,
    type,
    message || `Expected ${type}, got ${actualType}`
  );
}

function assertInstanceOf(value, constructor, message) {
  assert.ok(
    value instanceof constructor,
    message || `Expected instance of ${constructor.name}`
  );
}

// Usage
assertIsPositive(5);           // OK
assertArrayIncludes([1, 2, 3], 2);  // OK
assertType('hello', 'string'); // OK
assertInstanceOf(new Date(), Date); // OK

AssertionError#

import { strict as assert, AssertionError } from 'assert';

// Access AssertionError properties
try {
  assert.strictEqual(1, 2);
} catch (err) {
  if (err instanceof AssertionError) {
    console.log('Actual:', err.actual);     // 1
    console.log('Expected:', err.expected); // 2
    console.log('Operator:', err.operator); // 'strictEqual'
    console.log('Message:', err.message);
  }
}

// Create custom AssertionError
const error = new AssertionError({
  message: 'Custom assertion failed',
  actual: 'foo',
  expected: 'bar',
  operator: 'customAssert'
});

// Useful for custom assertions
function assertBetween(value, min, max) {
  if (value < min || value > max) {
    throw new AssertionError({
      message: `Expected ${value} to be between ${min} and ${max}`,
      actual: value,
      expected: `${min} <= value <= ${max}`,
      operator: 'assertBetween'
    });
  }
}

Validation Helpers#

import { strict as assert } from 'assert';

// Validation using assertions
function validateUser(user) {
  assert.ok(user, 'User is required');
  assert.ok(typeof user.name === 'string', 'Name must be a string');
  assert.ok(user.name.length >= 2, 'Name must be at least 2 characters');
  assert.match(user.email, /^\S+@\S+\.\S+$/, 'Invalid email format');
  assert.ok(Number.isInteger(user.age), 'Age must be an integer');
  assert.ok(user.age >= 0 && user.age <= 150, 'Age must be between 0 and 150');

  return true;
}

// Schema validation
function assertSchema(obj, schema) {
  for (const [key, validator] of Object.entries(schema)) {
    const value = obj[key];

    if (typeof validator === 'string') {
      assert.strictEqual(typeof value, validator, `${key} must be ${validator}`);
    } else if (typeof validator === 'function') {
      assert.ok(validator(value), `${key} failed validation`);
    } else if (validator instanceof RegExp) {
      assert.match(String(value), validator, `${key} format invalid`);
    }
  }
}

assertSchema(user, {
  name: 'string',
  age: 'number',
  email: /^\S+@\S+\.\S+$/,
  active: v => typeof v === 'boolean'
});

Best Practices#

Choosing Assertions:
✓ Use strict mode always
✓ Use deepStrictEqual for objects
✓ Use strictEqual for primitives
✓ Use throws/rejects for errors

Messages:
✓ Provide descriptive messages
✓ Include actual values in messages
✓ Make failures easy to debug
✓ Use template literals

Testing:
✓ One assertion per behavior
✓ Test edge cases
✓ Test error conditions
✓ Use async assertions for promises

Avoid:
✗ Legacy loose equality
✗ Catching AssertionErrors silently
✗ Too many assertions per test
✗ Using assert for user input validation

The Node.js assert module provides essential functions for testing and invariant checking. Always use strict mode (assert/strict) for reliable equality checks. Use throws and rejects for error testing, match for regex validation, and deepStrictEqual for object comparison. While assert is great for tests and development checks, consider proper validation libraries for user input validation in production code.