Module assert

Assertion library for unit testing. It implements the CommonJS Unit Testing specification and adds some additional convenience methods. All methods allow an additional argument: comment. This comment will be appended to the error message if an assertion fails.

Example

const assert = require("assert");
assert.deepEqual({b: 2, a: 1}, {a: 1, b: 2});
assert.deepEqual({b: 2, a: 1}, {a: 1, b: 2}, "optional comment");
assert.isFalse(100 != 100);
assert.isFalse(100 != 100, "optional comment");
assert.isNotNull(undefined);
assert.isNotNull(undefined, "optional comment");

See

The test module is a test runner for unit tests. It manages the execution of tests and provides the outcome to the user.

Functions

deepEqual (actual, expected)
equal (actual, expected)
fail (options)
isFalse (val)
isNaN (val)
isNotNaN (val)
isNotNull (val)
isNotUndefined (val)
isNull (val)
isTrue (val)
isUndefined (val)
matches (value, expr)
notDeepEqual (actual, expected)
notEqual (actual, expected)
notStrictEqual (actual, expected)
ok (value)
strictEqual (actual, expected)
stringContains (value, pattern)
throws (func, expectedError)

Class ArgumentsError

Class AssertionError

Instance Properties

actual
expected
message
name
stackTrace

ArgumentsError (message)

Creates a new ArgumentsError instance

Parameters

String

message

The exception message

Returns

A newly created ArgumentsError instance

ArgumentsError.prototype. message

ArgumentsError.prototype. stackTrace

AssertionError (options)

Constructs a new AssertionError instance

Parameters

Object

options

An object containing error details

AssertionError.prototype. actual

AssertionError.prototype. expected

AssertionError.prototype. message

AssertionError.prototype. name

AssertionError.prototype. stackTrace

deepEqual (actual, expected)

Performs a deep recursive comparison of objects. It is equivalent to equal(). If an object's property holds a non-object type, it performs a non-strict comparison. Instances of Date are compared with getTime() according to universal time.

Example

// passing assertions
assert.deepEqual(5, "5");
assert.deepEqual(
  { time: new Date(2010, 5, 14) },
  { "time": new Date(2010, 5, 14) }
);
assert.deepEqual([1, 2, 3], ["1", "2", "3"]);
assert.deepEqual({"one": 1, "two": 2}, {"two": "2", "one": "1"});

Parameters

Object	actual	The actual value
Object	expected	The expected value

Throws

ArgumentsError, AssertionError

equal (actual, expected)

Performs a non-strict comparison with the simple comparison operator == to check if the values are equal. When they are equal, the assertion passes, otherwise it fails.

Example

// truthy conditionals
assert.equal(true, true);
assert.equal(true, "1");

// falsy conditionals
assert.equal(false, false);
assert.equal(false, "");
assert.equal(false, "0");
assert.equal(null, undefined);

Parameters

Object	actual	The actual value
Object	expected	The expected value

Throws

ArgumentsError, AssertionError

fail (options)

Basic failure method. Fails an assertion without checking any preconditions.

Example

// a complex condition
if (a === true && (b === "complex" || ...)) {
  assert.fail("This should not be reached!");
}

Parameters

Object|String

options

An object containing optional "message", "actual" and "expected" properties, or alternatively a message string

Throws

AssertionError

isFalse (val)

Checks if the value passed as argument is strict boolean false using ===.

Example

// passing assertion
assert.isFalse(100 != 100);

// failing assertion
assert.isFalse(100 == 100);

Parameters

Object

val

The value that should be boolean false.

Throws

ArgumentsError, AssertionError

isNaN (val)

Asserts that the value passed as argument is NaN. Uses global.isNaN() for the check.

Parameters

Object

val

The value that should be NaN.

Throws

ArgumentsError, AssertionError

isNotNaN (val)

Checks if the value passed as argument is not NaN. Uses global.isNaN() for the check.

Parameters

Object

val

The value that should be not NaN.

Throws

ArgumentsError, AssertionError

isNotNull (val)

Checks if the value passed as argument is strict not null using ===.

Example

// passing assertions
assert.isNotNull(undefined);
assert.isNotNull("passes");

// failing assertion
assert.isNotNull(null);

Parameters

Object

val

The value that should be not null.

Throws

ArgumentsError, AssertionError

isNotUndefined (val)

Checks if the value passed as argument is not undefined using ===.

Example

// passing assertions
assert.isNotUndefined(null);
assert.isNotUndefined("passes");

// failing assertion
assert.isNotUndefined(undefined);

Parameters

Object

val

The value that should be not undefined.

Throws

ArgumentsError, AssertionError

isNull (val)

Checks if the value passed as argument is strict null using ===.

Example

// passing assertion
assert.isNull(null);

// failing assertions
assert.isNull(undefined);
assert.isNull("");

Parameters

Object

val

The value that should be null.

Throws

ArgumentsError, AssertionError

isTrue (val)

Checks if the value passed as argument is boolean true using ===.

Example

// passing assertion
assert.isTrue(100 == 100);

// failing assertion
assert.isTrue(100 != 100);

Parameters

Object

val

The value that should be boolean true.

Throws

ArgumentsError, AssertionError

isUndefined (val)

Checks if the value passed as argument is strict undefined using ===.

Example

// passing assertion
assert.isUndefined(undefined);

// failing assertions
assert.isUndefined(null);
assert.isUndefined("");

Parameters

Object

val

The value that should be undefined.

Throws

ArgumentsError, AssertionError

matches (value, expr)

Checks if the regular expression matches the string.

Example

assert.matches("this will pass", /p.?[s]{2}/);
assert.matches("this will fail", /[0-9]+/);

Parameters

String	value	The string that should contain the regular expression pattern
RegExp	expr	The regular expression that should match the value

Throws

ArgumentsError, AssertionError

notDeepEqual (actual, expected)

Performs a deep recursive comparison of objects. The comparison is equivalent to notEqual().

Example

// passing assertions
assert.notDeepEqual(
  { "time": new Date(2010, 5, 14) },
  { "time": new Date(2010, 5, 15) }
);
assert.notDeepEqual([1, 2, 3, 4], ["1", "2", "3"]);
assert.notDeepEqual({"one": 1, "two": 2}, {"three": "3", "one": "1"});

Parameters

Object	actual	The actual value
Object	expected	The expected value

Throws

ArgumentsError, AssertionError

notEqual (actual, expected)

Performs a non-strict comparison with the simple comparison operator != to check if the values are not equal. When they are not equal, the assertion passes, otherwise it fails.

Example

// passing assertions
assert.notEqual(true, false);
assert.notEqual(1, 2);
assert.notEqual(false, NaN);
assert.notEqual(null, NaN);
assert.notEqual(undefined, NaN);

Parameters

Object	actual	The actual value
Object	expected	The expected value

Throws

ArgumentsError, AssertionError

notStrictEqual (actual, expected)

Performs a strict comparison with the strict inequality operator !==. When the values are inequal in type and value, the assertion passes, otherwise it fails.

Example

// passing assertions
assert.notStrictEqual(null, undefined);
assert.notStrictEqual(1, "1");
assert.notStrictEqual(true, false);

Parameters

Object	actual	The actual value
Object	expected	The expected value

Throws

ArgumentsError, AssertionError

ok (value)

Checks if the value passed as argument is truthy.

Example

// passing assertions
assert.ok(true);
assert.ok("1");
assert.ok([]);
assert.ok({});
assert.ok(new Boolean(false));
assert.ok(Infinity);

// failing assertions
assert.ok(0);
assert.ok(false);
assert.ok(null);
assert.ok(undefined);
assert.ok("");

Parameters

Object

value

The value to check for truthiness

Throws

ArgumentsError, AssertionError

strictEqual (actual, expected)

Performs a strict comparison with the strict equality operator ===. When the values are equal in type and value, the assertion passes, otherwise it fails.

Example

// passing assertions
assert.strictEqual(null, null);
assert.strictEqual(undefined, undefined);
assert.strictEqual(1, 1);
assert.strictEqual("1", "1");
assert.strictEqual(true, true);

// passing assertion
var obj = {};
assert.strictEqual(obj, obj);

// failing assertions
assert.strictEqual(null, undefined);
assert.strictEqual(true, "1");
assert.strictEqual(false, "");
assert.strictEqual(false, "0");

Parameters

Object	actual	The actual value
Object	expected	The expected value

Throws

ArgumentsError, AssertionError

stringContains (value, pattern)

Checks if the value passed as argument contains the pattern specified.

Example

assert.stringContains("this will pass", "pass");
assert.stringContains("this will fail", "pass");

Parameters

String	value	The string that should contain the pattern
String	pattern	The string that should be contained

Throws

ArgumentsError, AssertionError

throws (func, expectedError)

Checks if the function passed as argument throws a defined exception. It can also assert certain Java exceptions thrown by the function.

Example

var foo = function() { throw "foo"; };
var bar = function() { (new java.util.Vector()).get(0); }

// passes
assert.throws(foo, "foo");

// fails
assert.throws(foo, "bar");

// checks for a Java runtime exception, passes
assert.throws(bar, java.lang.ArrayIndexOutOfBoundsException);

Parameters

Object	func	The function to call
Object	expectedError	Optional object expected to be thrown when executing the function

Throws

ArgumentsError, AssertionError

1.2.1

• Overview • Module Index