RingoJS

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

Class ArgumentsError

Instance Properties

Class AssertionError

Instance Properties


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 (value)

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 value

The value that should be boolean false.

Throws

ArgumentsError, AssertionError

isNaN (value)

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

Parameters

Object value

The value that should be NaN.

Throws

ArgumentsError, AssertionError

isNotNaN (value)

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

Parameters

Object value

The value that should be not NaN.

Throws

ArgumentsError, AssertionError

isNotNull (value)

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 value

The value that should be not null.

Throws

ArgumentsError, AssertionError

isNotUndefined (value)

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 value

The value that should be not undefined.

Throws

ArgumentsError, AssertionError

isNull (value)

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 value

The value that should be null.

Throws

ArgumentsError, AssertionError

isTrue (value)

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 value

The value that should be boolean true.

Throws

ArgumentsError, AssertionError

isUndefined (value)

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 value

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 const 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

const foo = function() { throw "foo"; };
const 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