Node.js Assert Module: Equal vs Strict Equal vs Deep Equal – What’s the Difference?

Table of Contents#

1. What is the Node.js Assert Module?
2. A Quick Refresher: == vs === in JavaScript
3. Understanding assert.equal()
4. Understanding assert.strictEqual()
5. Understanding assert.deepEqual()
6. Key Differences at a Glance
7. Practical Examples
8. Common Pitfalls and How to Avoid Them
9. When to Use Each Method
10. Conclusion
11. References

What is the Node.js Assert Module?#

The assert module is a built-in Node.js utility for writing assertions in tests or validation logic. It provides functions to check if a condition is true; if not, it throws an AssertionError with a custom message (optional). Think of it as a way to “assert” that something must be true for your code to work correctly.

While it’s not a full-featured testing framework (like Jest or Mocha), the assert module is lightweight and useful for simple validations, debugging, or small-scale testing. Its methods include equal(), strictEqual(), deepEqual(), and more, each tailored to specific equality checks.

A Quick Refresher: == vs === in JavaScript#

Before diving into the assert methods, let’s recap JavaScript’s equality operators—they’re the foundation for how these methods work:

• Loose Equality (==): Compares values after type coercion (i.e., converting operands to the same type). For example, 5 == '5' is true because the string '5' is coerced to the number 5.
• Strict Equality (===): Compares values without type coercion. Both the value and type must match. For example, 5 === '5' is false (number vs. string).

This distinction is critical: assert.equal() uses ==, assert.strictEqual() uses ===, and assert.deepEqual() uses == with special handling for objects/arrays.

Understanding assert.equal()#

Definition#

assert.equal(actual, expected[, message]) tests if actual is loosely equal to expected using the == operator. If not, it throws an AssertionError with the optional message.

How It Works#

• Uses loose equality (==), so type coercion occurs.
• Compares primitives directly (e.g., numbers, strings, booleans) after coercion.
• Not recommended for objects/arrays (use deepEqual() instead).

Parameters#

• actual: The value to test (e.g., a variable, function return value).
• expected: The value to compare against actual.
• message (optional): Custom error message if the assertion fails.

Examples#

Passing Case (Type Coercion)#

const assert = require('assert');
 
// 5 (number) == '5' (string) → true (coercion)
assert.equal(5, '5', '5 should equal "5" with loose equality'); 
 
// true == 1 → true (boolean true coerces to 1)
assert.equal(true, 1, 'true should equal 1 with loose equality'); 

Failing Case (No Coercion Match)#

// 5 (number) == 6 (number) → false (values differ)
assert.equal(5, 6, '5 should equal 6'); 
// Throws: AssertionError [ERR_ASSERTION]: 5 should equal 6

Notes#

• Avoid equal() for type-sensitive checks (e.g., validating user input where '10' and 10 are distinct).
• Never use equal() with objects/arrays—it compares references, not content (e.g., {a: 1} == {a: 1} is false because they’re different objects in memory).

Understanding assert.strictEqual()#

Definition#

assert.strictEqual(actual, expected[, message]) tests if actual is strictly equal to expected using the === operator. It checks both value and type, with no coercion.

How It Works#

• Uses strict equality (===), so no type coercion occurs.
• Both actual and expected must have the same value and type to pass.
• Ideal for primitives (numbers, strings, booleans, null, undefined).

Parameters#

Same as assert.equal(): actual, expected, and optional message.

Examples#

Passing Case (Same Type and Value)#

const assert = require('assert');
 
// 5 (number) === 5 (number) → true
assert.strictEqual(5, 5, '5 should strictly equal 5'); 
 
// 'hello' (string) === 'hello' (string) → true
assert.strictEqual('hello', 'hello', 'Strings should match strictly'); 
 
// false (boolean) === false (boolean) → true
assert.strictEqual(false, false, 'Booleans should match strictly'); 

Failing Case (Type Mismatch)#

// 5 (number) === '5' (string) → false (different types)
assert.strictEqual(5, '5', '5 should strictly equal "5"'); 
// Throws: AssertionError [ERR_ASSERTION]: 5 should strictly equal "5"

Notes#

• Preferred for primitives where type matters (e.g., validating that an API returns a number, not a string).
• Like equal(), strictEqual() compares object references, not content (e.g., {a:1} === {a:1} is false).

Understanding assert.deepEqual()#

Definition#

assert.deepEqual(actual, expected[, message]) tests if actual and expected are deeply equal. It recursively compares the structure and values of objects, arrays, and other complex types using loose equality (==) for nested values.

How It Works#

• For primitives: Uses == (same as assert.equal()).
• For objects/arrays: Recursively checks if all own enumerable properties (for objects) or elements (for arrays) are loosely equal.
• Special cases:
  • NaN is considered equal to NaN (even though NaN == NaN is false in vanilla JS).
  • -0 and +0 are considered equal (unlike Object.is(-0, +0), which is false).
  • Ignores object prototypes and non-enumerable properties (only checks own enumerable properties).

Parameters#

Same as the above methods: actual, expected, optional message.

Examples#

Passing Case (Deep Object Comparison)#

const assert = require('assert');
 
// Objects with same properties and loosely equal values
const obj1 = { a: 1, b: '2' };
const obj2 = { a: '1', b: 2 }; // 1 == '1' and '2' == 2 (loose equality)
assert.deepEqual(obj1, obj2, 'Objects should be deeply equal'); 
 
// Arrays with loosely equal elements
const arr1 = [1, '3', NaN];
const arr2 = ['1', 3, NaN]; // 1 == '1', '3' == 3, NaN == NaN (special case)
assert.deepEqual(arr1, arr2, 'Arrays should be deeply equal'); 

Failing Case (Mismatched Structure)#

// Objects with different properties
const objA = { a: 1, b: 2 };
const objB = { a: 1 }; 
assert.deepEqual(objA, objB, 'Objects should have the same properties'); 
// Throws: AssertionError [ERR_ASSERTION]: Objects should have the same properties

Notes#

• Use deepEqual() for comparing complex data structures (e.g., API responses, configuration objects).
• Not strict for nested values: If you need strict equality (e.g., 1 vs '1' in nested properties), use assert.deepStrictEqual() instead (it uses === for nested values).

Key Differences at a Glance#

Practical Examples#

Let’s walk through real-world scenarios to see how these methods behave.

Scenario 1: Validating User Input#

Suppose you’re building a login form where the user must enter their age as a number. You want to reject strings like '25' and accept only numeric 25.

const assert = require('assert');
 
function validateAge(age) {
  assert.strictEqual(typeof age, 'number', 'Age must be a number'); 
  // Using strictEqual ensures age is a number (not string)
}
 
validateAge(25); // Passes
validateAge('25'); // Throws: AssertionError: Age must be a number

Scenario 2: Comparing API Responses#

You’re testing an API that returns user data. You want to ensure the response structure and values match your expectations (even if some values are loosely equal).

const assert = require('assert');
 
const expectedUser = { id: 1, name: 'Alice', isActive: 'true' }; 
const actualUser = { id: '1', name: 'Alice', isActive: true }; 
 
// deepEqual uses == for nested values: 1 == '1' and 'true' == true → passes
assert.deepEqual(actualUser, expectedUser, 'User data mismatch'); 

Common Pitfalls and How to Avoid Them#

1. Using equal()/strictEqual() for Objects#

Pitfall: assert.equal({a:1}, {a:1}) or assert.strictEqual({a:1}, {a:1}) will always fail—they compare references, not content.
Fix: Use assert.deepEqual() for objects/arrays.

2. Relying on deepEqual() for Strict Nested Values#

Pitfall: deepEqual({a: 1}, {a: '1'}) passes because 1 == '1', but you may want to enforce type consistency.
Fix: Use assert.deepStrictEqual() (strict equality for nested values).

3. Forgetting NaN Quirks#

Pitfall: assert.equal(NaN, NaN) fails (since NaN == NaN is false), but assert.deepEqual(NaN, NaN) passes (special handling for NaN).
Fix: Use deepEqual() when comparing values that might be NaN.

When to Use Each Method#

Conclusion#

The Node.js assert module’s equal(), strictEqual(), and deepEqual() methods serve distinct purposes:

• equal() uses loose equality (==) with coercion—use cautiously.
• strictEqual() uses strict equality (===)—preferred for primitives.
• deepEqual() recursively checks objects/arrays with loose equality—ideal for complex structures.

By choosing the right method, you’ll write more reliable tests and avoid subtle bugs caused by unintended type coercion or reference comparisons.

References#

• Node.js Assert Module Documentation
• MDN: Equality Operators (== vs ===)
• Node.js deepEqual vs deepStrictEqual