1 assert module

1.1 INTRODUCTION

The assert module is a built-in module of Node, which is mainly used for assertion. If the expression does not meet expectations, an error is thrown. The module provides 11 methods, but only a few are commonly used.

1.2 common methods

1.2.1 assert()

The assert method takes two parameters. When the Boolean value corresponding to the first parameter is true, there is no prompt and undefined is returned. When the Boolean value corresponding to the first parameter is false, an error will be thrown, and the error prompt is the string set by the second parameter.

// format
assert(value, message)

// Example
var assert = require('assert');

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

var expected = add(1,2);
assert( expected === 3, 'Expected 1 + 2 equals 3');

The above code will not have any output because the first parameter of the assert method is true.

assert( expected === 4, 'Expected 1 + 2 equals 3')
// AssertionError: expected 1 plus 2 equal to 3

The above code throws an error because the first parameter of the assert method is false.

1.2.2 assert.ok()

ok is another name of the assert method, exactly the same as the assert method.

1.2.3 assert.equal()

The equal method takes three parameters, the first is the actual value, the second is the expected value, and the third is the error message.

// format
assert.equal(actual, expected, [message])

assert.equal(true, value, message);
// Equate to
assert(value, message);

// Example
var assert = require('assert');

function add (a, b) {
  return a + b;
}
var expected = add(1,2);
// The following three sentences have the same effect
assert(expected == 3, 'Expected 1+2 Equal to 3');
assert.ok(expected == 3, 'Expected 1+2 Equal to 3');
assert.equal(expected, 3, 'Expected 1+2 Equal to 3');

The equal method uses the equality operator (= =), rather than the strict operator (= =), for comparison.

1.2.4 assert.notEqual()

The use of the notEqual method is similar to that of the equal method, but an error is thrown only if the actual value is equal to the expected value.

// format
assert.notEqual(actual, expected, [message])

// usage
var assert = require('assert');

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

var expected = add(1,2);

// The following three writing methods have the same effect
assert(expected != 4, 'Expected not equal to 4');
assert.ok(expected != 4, 'Expected not equal to 4');
assert.notEqual(expected, 4, 'Expected not equal to 4');

The notEqual method uses the inequality operator (! =), rather than the strict inequality operator (! = =), for comparison.

1.2.5 assert.deepEqual()

The deepEqual method is used to compare two objects. As long as their attributes correspond one by one and their values are equal, two objects are considered equal. Otherwise, an error is thrown.

// format
assert.deepEqual(actual, expected, [message])

// Example
var assert = require('assert');

var list1 = [1, 2, 3, 4, 5];
var list2 = [1, 2, 3, 4, 5];

assert.deepEqual(list1, list2, 'Two arrays are expected to have the same properties');

var person1 = { "name":"john", "age":"21" };
var person2 = { "name":"john", "age":"21" };

assert.deepEqual(person1, person2, 'Two objects are expected to have the same properties');

1.2.6 assert.notDeepEqual()

The notDeepEqual method is the opposite of the deepEqual method, which is used to assert whether two objects are not equal.

// format
assert.notDeepEqual(actual, expected, [message])

// Example
var assert = require('assert');

var list1 = [1, 2, ,3, 4, 5];
var list2 = [1, 2, 3, 4, 5];

assert.notDeepEqual(list1, list2, 'Two objects are not expected to be equal');

var person1 = { "name":"john", "age":"21" };
var person2 = { "name":"jane", "age":"19" };

// deepEqual checks the elements in the objects are identical
assert.notDeepEqual(person1, person2, 'Two objects are not expected to be equal');

1.2.7 assert.strictEqual()

The strictEqual method uses the strict equality operator (=====), which compares two expressions.

// format
assert.strictEqual(actual, expected, [message])

// Example
var assert = require('assert');

assert.strictEqual(1, '1', 'Expected strictly equal');
// AssertionError: expected strict equality

1.2.8 assert.notStrictEqual()

The assert.notStrictEqual method uses the strict inequality operator (! = =), which compares two expressions.

// format
assert.notStrictEqual(actual, expected, [message])

// Example
var assert = require('assert');

assert.notStrictEqual(1, true, 'Strictly unequal expectations');

1.2.9 assert.throws()

The throws method expects an error to be thrown by a block of code that meets the specified criteria.

// format
assert.throws(block, [error], [message])

// For example, the error thrown matches a constructor
assert.throws(
  function() {
    throw new Error("Wrong value");
  },
  Error,
  'Unexpected error type'
);

// Example 2: the prompt for throwing an error conforms to the regular expression
assert.throws(
  function() {
    throw new Error("Wrong value");
  },
  /value/,
  'Unexpected error type'
);

// Example 3: the error thrown conforms to the verification of the user-defined function
assert.throws(
  function() {
    throw new Error("Wrong value");
  },
  function(err) {
    if ( (err instanceof Error) && /value/.test(err) ) {
      return true;
    }
  },
  'Unexpected error type'
);

1.2.10 assert.doesNotThrow()

The doesnotthow method is the opposite of the throws method, expecting a block of code to not throw an error.

// format
assert.doesNotThrow(block, [message])

// usage
assert.doesNotThrow(
  function() {
    console.log("Nothing to see here");
  },
  'Expected no error thrown'
);

1.2.10 assert.ifError()

ifError method asserts whether an expression is false. If the Boolean value corresponding to the expression is equal to true, an error is thrown. It is useful for verifying the first parameter of a callback function, and if it is true, it indicates an error.

// format
assert.ifError(value)

// usage
function sayHello(name, callback) {
  var error = false;
  var str   = "Hello "+name;
  callback(error, str);
}

// use the function
sayHello('World', function(err, value){
  assert.ifError(err);
  // ...
})

1.2.11 assert.fail()

The fail method is used to throw an error.

// format
assert.fail(actual, expected, message, operator)

// Example
var assert = require('assert');
assert.fail(21, 42, 'Test Failed', '###')
// AssertionError: Test Failed
assert.fail(21, 21, 'Test Failed', '###')
// AssertionError: Test Failed
assert.fail(21, 42, undefined, '###')
// AssertionError: 21 ### 42

The method has four parameters, but it always throws an error regardless of the value of the parameter.
If the Boolean value corresponding to the message parameter is not false, the error message thrown is message, otherwise the error message is "actual value + separator + expected value".