Assert

The assert style is very similar to node.js' included assert module, with a bit of extra sugar. Of the three style options, assert is the only one that is not chainable. Check out the Style Guide for a comparison.

API Reference

assert(expression, message)

  • @param{ Mixed }expressionto test for truthiness
  • @param{ String }messageto display on error

Write your own test expressions.

assert('foo' !== 'bar', 'foo is not bar');
assert(Array.isArray([]), 'empty arrays are arrays');

.fail(actual, expected, [message], [operator])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message
  • @param{ String }operator

Throw a failure. Node.js assert module-compatible.

.ok(object, [message])

  • @param{ Mixed }objectto test
  • @param{ String }message

Asserts that object is truthy.

assert.ok('everything', 'everything is ok');
assert.ok(false, 'this will fail');

.notOk(object, [message])

  • @param{ Mixed }objectto test
  • @param{ String }message

Asserts that object is falsy.

assert.notOk('everything', 'this will fail');
assert.notOk(false, 'this will pass');

.equal(actual, expected, [message])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message

Asserts non-strict equality (==) of actual and expected.

assert.equal(3, '3', '== coerces values to strings');

.notEqual(actual, expected, [message])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message

Asserts non-strict inequality (!=) of actual and expected.

assert.notEqual(3, 4, 'these numbers are not equal');

.strictEqual(actual, expected, [message])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message

Asserts strict equality (===) of actual and expected.

assert.strictEqual(true, true, 'these booleans are strictly equal');

.notStrictEqual(actual, expected, [message])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message

Asserts strict inequality (!==) of actual and expected.

assert.notStrictEqual(3, '3', 'no coercion for strict equality');

.deepEqual(actual, expected, [message])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message

Asserts that actual is deeply equal to expected.

assert.deepEqual({ tea: 'green' }, { tea: 'green' });

.notDeepEqual(actual, expected, [message])

  • @param{ Mixed }actual
  • @param{ Mixed }expected
  • @param{ String }message

Assert that actual is not deeply equal to expected.

assert.notDeepEqual({ tea: 'green' }, { tea: 'jasmine' });

.isTrue(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is true.

var teaServed = true;
assert.isTrue(teaServed, 'the tea has been served');

.isFalse(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is false.

var teaServed = false;
assert.isFalse(teaServed, 'no tea yet? hmm...');

.isNull(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is null.

assert.isNull(err, 'there was no error');

.isNotNull(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not null.

var tea = 'tasty chai';
assert.isNotNull(tea, 'great, time for tea!');

.isUndefined(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is undefined.

var tea;
assert.isUndefined(tea, 'no tea defined');

.isDefined(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not undefined.

var tea = 'cup of chai';
assert.isDefined(tea, 'tea has been defined');

.isFunction(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is a function.

function serveTea() { return 'cup of tea'; };
assert.isFunction(serveTea, 'great, we can have tea now');

.isNotFunction(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not a function.

var serveTea = [ 'heat', 'pour', 'sip' ];
assert.isNotFunction(serveTea, 'great, we have listed the steps');

.isObject(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is an object (as revealed by Object.prototype.toString).

var selection = { name: 'Chai', serve: 'with spices' };
assert.isObject(selection, 'tea selection is an object');

.isNotObject(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not an object.

var selection = 'chai'
assert.isNotObject(selection, 'tea selection is not an object');
assert.isNotObject(null, 'null is not an object');

.isArray(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is an array.

var menu = [ 'green', 'chai', 'oolong' ];
assert.isArray(menu, 'what kind of tea do we want?');

.isNotArray(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not an array.

var menu = 'green|chai|oolong';
assert.isNotArray(menu, 'what kind of tea do we want?');

.isString(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is a string.

var teaOrder = 'chai';
assert.isString(teaOrder, 'order placed');

.isNotString(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not a string.

var teaOrder = 4;
assert.isNotString(teaOrder, 'order placed');

.isNumber(value, [message])

  • @param{ Number }value
  • @param{ String }message

Asserts that value is a number.

var cups = 2;
assert.isNumber(cups, 'how many cups');

.isNotNumber(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not a number.

var cups = '2 cups please';
assert.isNotNumber(cups, 'how many cups');

.isBoolean(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is a boolean.

var teaReady = true
  , teaServed = false;

assert.isBoolean(teaReady, 'is the tea ready');
assert.isBoolean(teaServed, 'has tea been served');

.isNotBoolean(value, [message])

  • @param{ Mixed }value
  • @param{ String }message

Asserts that value is not a boolean.

var teaReady = 'yep'
  , teaServed = 'nope';

assert.isNotBoolean(teaReady, 'is the tea ready');
assert.isNotBoolean(teaServed, 'has tea been served');

.typeOf(value, name, [message])

  • @param{ Mixed }value
  • @param{ String }name
  • @param{ String }message

Asserts that value's type is name, as determined by Object.prototype.toString.

assert.typeOf({ tea: 'chai' }, 'object', 'we have an object');
assert.typeOf(['chai', 'jasmine'], 'array', 'we have an array');
assert.typeOf('tea', 'string', 'we have a string');
assert.typeOf(/tea/, 'regexp', 'we have a regular expression');
assert.typeOf(null, 'null', 'we have a null');
assert.typeOf(undefined, 'undefined', 'we have an undefined');

.notTypeOf(value, name, [message])

  • @param{ Mixed }value
  • @param{ String }typeofname
  • @param{ String }message

Asserts that value's type is not name, as determined by Object.prototype.toString.

assert.notTypeOf('tea', 'number', 'strings are not numbers');

.instanceOf(object, constructor, [message])

  • @param{ Object }object
  • @param{ Constructor }constructor
  • @param{ String }message

Asserts that value is an instance of constructor.

var Tea = function (name) { this.name = name; }
  , chai = new Tea('chai');

assert.instanceOf(chai, Tea, 'chai is an instance of tea');

.notInstanceOf(object, constructor, [message])

  • @param{ Object }object
  • @param{ Constructor }constructor
  • @param{ String }message

Asserts value is not an instance of constructor.

var Tea = function (name) { this.name = name; }
  , chai = new String('chai');

assert.notInstanceOf(chai, Tea, 'chai is not an instance of tea');

.include(haystack, needle, [message])

  • @param{ Array | String }haystack
  • @param{ Mixed }needle
  • @param{ String }message

Asserts that haystack includes needle. Works for strings and arrays.

assert.include('foobar', 'bar', 'foobar contains string "bar"');
assert.include([ 1, 2, 3 ], 3, 'array contains value');

.notInclude(haystack, needle, [message])

  • @param{ Array | String }haystack
  • @param{ Mixed }needle
  • @param{ String }message

Asserts that haystack does not include needle. Works for strings and arrays. i assert.notInclude('foobar', 'baz', 'string not include substring'); assert.notInclude([ 1, 2, 3 ], 4, 'array not include contain value');

.match(value, regexp, [message])

  • @param{ Mixed }value
  • @param{ RegExp }regexp
  • @param{ String }message

Asserts that value matches the regular expression regexp.

assert.match('foobar', /^foo/, 'regexp matches');

.notMatch(value, regexp, [message])

  • @param{ Mixed }value
  • @param{ RegExp }regexp
  • @param{ String }message

Asserts that value does not match the regular expression regexp.

assert.notMatch('foobar', /^foo/, 'regexp does not match');

.property(object, property, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ String }message

Asserts that object has a property named by property.

assert.property({ tea: { green: 'matcha' }}, 'tea');

.notProperty(object, property, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ String }message

Asserts that object does not have a property named by property.

assert.notProperty({ tea: { green: 'matcha' }}, 'coffee');

.deepProperty(object, property, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ String }message

Asserts that object has a property named by property, which can be a string using dot- and bracket-notation for deep reference.

assert.deepProperty({ tea: { green: 'matcha' }}, 'tea.green');

.notDeepProperty(object, property, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ String }message

Asserts that object does not have a property named by property, which can be a string using dot- and bracket-notation for deep reference.

assert.notDeepProperty({ tea: { green: 'matcha' }}, 'tea.oolong');

.propertyVal(object, property, value, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ Mixed }value
  • @param{ String }message

Asserts that object has a property named by property with value given by value.

assert.propertyVal({ tea: 'is good' }, 'tea', 'is good');

.propertyNotVal(object, property, value, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ Mixed }value
  • @param{ String }message

Asserts that object has a property named by property, but with a value different from that given by value.

assert.propertyNotVal({ tea: 'is good' }, 'tea', 'is bad');

.deepPropertyVal(object, property, value, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ Mixed }value
  • @param{ String }message

Asserts that object has a property named by property with value given by value. property can use dot- and bracket-notation for deep reference.

assert.deepPropertyVal({ tea: { green: 'matcha' }}, 'tea.green', 'matcha');

.deepPropertyNotVal(object, property, value, [message])

  • @param{ Object }object
  • @param{ String }property
  • @param{ Mixed }value
  • @param{ String }message

Asserts that object has a property named by property, but with a value different from that given by value. property can use dot- and bracket-notation for deep reference.

assert.deepPropertyNotVal({ tea: { green: 'matcha' }}, 'tea.green', 'konacha');

.lengthOf(object, length, [message])

  • @param{ Mixed }object
  • @param{ Number }length
  • @param{ String }message

Asserts that object has a length property with the expected value.

assert.lengthOf([1,2,3], 3, 'array has length of 3');
assert.lengthOf('foobar', 5, 'string has length of 6');

.throws(function, [constructor/string/regexp], [string/regexp], [message])

Asserts that function will throw an error that is an instance of constructor, or alternately that it will throw an error with message matching regexp.

assert.throw(fn, 'function throws a reference error');
assert.throw(fn, /function throws a reference error/);
assert.throw(fn, ReferenceError);
assert.throw(fn, ReferenceError, 'function throws a reference error');
assert.throw(fn, ReferenceError, /function throws a reference error/);

.doesNotThrow(function, [constructor/regexp], [message])

Asserts that function will not throw an error that is an instance of constructor, or alternately that it will not throw an error with message matching regexp.

assert.doesNotThrow(fn, Error, 'function does not throw');

.operator(val1, operator, val2, [message])

  • @param{ Mixed }val1
  • @param{ String }operator
  • @param{ Mixed }val2
  • @param{ String }message

Compares two values using operator.

assert.operator(1, '<', 2, 'everything is ok');
assert.operator(1, '>', 2, 'this will fail');

.closeTo(actual, expected, delta, [message])

  • @param{ Number }actual
  • @param{ Number }expected
  • @param{ Number }delta
  • @param{ String }message

Asserts that the target is equal expected, to within a +/- delta range.

assert.closeTo(1.5, 1, 0.5, 'numbers are close');

.sameMembers(set1, set2, [message])

  • @param{ Array }superset
  • @param{ Array }subset
  • @param{ String }message

Asserts that set1 and set2 have the same members. Order is not taken into account.

assert.sameMembers([ 1, 2, 3 ], [ 2, 1, 3 ], 'same members');

.includeMembers(superset, subset, [message])

  • @param{ Array }superset
  • @param{ Array }subset
  • @param{ String }message

Asserts that subset is included in superset. Order is not taken into account.

assert.includeMembers([ 1, 2, 3 ], [ 2, 1 ], 'include members');