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)
Write your own test expressions.
assert('foo' !== 'bar', 'foo is not bar');
assert(Array.isArray([]), 'empty arrays are arrays');
.isOk(object, [message])
Asserts that object is truthy.
assert.isOk('everything', 'everything is ok');
assert.isOk(false, 'this will fail');
.isNotOk(object, [message])
Asserts that object is falsy.
assert.isNotOk('everything', 'this will fail');
assert.isNotOk(false, 'this will pass');
.equal(actual, expected, [message])
Asserts non-strict equality (==) of actual and expected.
assert.equal(3, '3', '== coerces values to strings');
.notEqual(actual, expected, [message])
Asserts non-strict inequality (!=) of actual and expected.
assert.notEqual(3, 4, 'these numbers are not equal');
.strictEqual(actual, expected, [message])
Asserts strict equality (===) of actual and expected.
assert.strictEqual(true, true, 'these booleans are strictly equal');
.notStrictEqual(actual, expected, [message])
Asserts strict inequality (!==) of actual and expected.
assert.notStrictEqual(3, '3', 'no coercion for strict equality');
.deepEqual(actual, expected, [message])
Asserts that actual is deeply equal to expected.
assert.deepEqual({ tea: 'green' }, { tea: 'green' });
.notDeepEqual(actual, expected, [message])
Assert that actual is not deeply equal to expected.
assert.notDeepEqual({ tea: 'green' }, { tea: 'jasmine' });
.isAbove(valueToCheck, valueToBeAbove, [message])
Asserts valueToCheck is strictly greater than (>) valueToBeAbove
assert.isAbove(5, 2, '5 is strictly greater than 2');
.isAtLeast(valueToCheck, valueToBeAtLeast, [message])
Asserts valueToCheck is greater than or equal to (>=) valueToBeAtLeast
assert.isAtLeast(5, 2, '5 is greater or equal to 2');
assert.isAtLeast(3, 3, '3 is greater or equal to 3');
.isBelow(valueToCheck, valueToBeBelow, [message])
Asserts valueToCheck is strictly less than (<) valueToBeBelow
assert.isBelow(3, 6, '3 is strictly less than 6');
.isAtMost(valueToCheck, valueToBeAtMost, [message])
Asserts valueToCheck is less than or equal to (<=) valueToBeAtMost
assert.isAtMost(3, 6, '3 is less than or equal to 6');
assert.isAtMost(4, 4, '4 is less than or equal to 4');
.isTrue(value, [message])
Asserts that value is true.
var teaServed = true;
assert.isTrue(teaServed, 'the tea has been served');
.isNotTrue(value, [message])
Asserts that value is not true.
var tea = 'tasty chai';
assert.isNotTrue(tea, 'great, time for tea!');
.isFalse(value, [message])
Asserts that value is false.
var teaServed = false;
assert.isFalse(teaServed, 'no tea yet? hmm...');
.isNotFalse(value, [message])
Asserts that value is not false.
var tea = 'tasty chai';
assert.isNotFalse(tea, 'great, time for tea!');
.isNotNull(value, [message])
Asserts that value is not null.
var tea = 'tasty chai';
assert.isNotNull(tea, 'great, time for tea!');
.isUndefined(value, [message])
Asserts that value is undefined.
var tea;
assert.isUndefined(tea, 'no tea defined');
.isDefined(value, [message])
Asserts that value is not undefined.
var tea = 'cup of chai';
assert.isDefined(tea, 'tea has been defined');
.isFunction(value, [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])
Asserts that value is not a function.
var serveTea = [ 'heat', 'pour', 'sip' ];
assert.isNotFunction(serveTea, 'great, we have listed the steps');
.isObject(value, [message])
Asserts that value is an object of type ‘Object’ (as revealed by Object.prototype.toString).
The assertion does not match subclassed objects.
var selection = { name: 'Chai', serve: 'with spices' };
assert.isObject(selection, 'tea selection is an object');
.isNotObject(value, [message])
Asserts that value is not an object of type ‘Object’ (as revealed by Object.prototype.toString).
var selection = 'chai'
assert.isNotObject(selection, 'tea selection is not an object');
assert.isNotObject(null, 'null is not an object');
.isArray(value, [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])
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])
Asserts that value is a string.
var teaOrder = 'chai';
assert.isString(teaOrder, 'order placed');
.isNotString(value, [message])
Asserts that value is not a string.
var teaOrder = 4;
assert.isNotString(teaOrder, 'order placed');
.isNumber(value, [message])
Asserts that value is a number.
var cups = 2;
assert.isNumber(cups, 'how many cups');
.isNotNumber(value, [message])
Asserts that value is not a number.
var cups = '2 cups please';
assert.isNotNumber(cups, 'how many cups');
.isBoolean(value, [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])
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])
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])
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])
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])
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])
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])
Asserts that haystack does not include needle. Works
for strings and arrays.
assert.notInclude('foobar', 'baz', 'string not include substring');
assert.notInclude([ 1, 2, 3 ], 4, 'array not include contain value');
.match(value, regexp, [message])
Asserts that value matches the regular expression regexp.
assert.match('foobar', /^foo/, 'regexp matches');
.notMatch(value, regexp, [message])
Asserts that value does not match the regular expression regexp.
assert.notMatch('foobar', /^foo/, 'regexp does not match');
.property(object, property, [message])
Asserts that object has a property named by property.
assert.property({ tea: { green: 'matcha' }}, 'tea');
.notProperty(object, property, [message])
Asserts that object does not have a property named by property.
assert.notProperty({ tea: { green: 'matcha' }}, 'coffee');
.deepProperty(object, property, [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])
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])
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])
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])
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])
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])
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', 6, '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.throws(fn, 'function throws a reference error');
assert.throws(fn, /function throws a reference error/);
assert.throws(fn, ReferenceError);
assert.throws(fn, ReferenceError, 'function throws a reference error');
assert.throws(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])
Compares two values using operator.
assert.operator(1, '<', 2, 'everything is ok');
assert.operator(1, '>', 2, 'this will fail');
.closeTo(actual, expected, delta, [message])
Asserts that the target is equal expected, to within a +/- delta range.
assert.closeTo(1.5, 1, 0.5, 'numbers are close');
.approximately(actual, expected, delta, [message])
Asserts that the target is equal expected, to within a +/- delta range.
assert.approximately(1.5, 1, 0.5, 'numbers are close');
.sameMembers(set1, set2, [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');
.sameDeepMembers(set1, set2, [message])
Asserts that set1 and set2 have the same members - using a deep equality checking.
Order is not taken into account.
assert.sameDeepMembers([ {b: 3}, {a: 2}, {c: 5} ], [ {c: 5}, {b: 3}, {a: 2} ], 'same deep members');
.includeMembers(superset, subset, [message])
Asserts that subset is included in superset.
Order is not taken into account.
assert.includeMembers([ 1, 2, 3 ], [ 2, 1 ], 'include members');
.includeDeepMembers(superset, subset, [message])
Asserts that subset is included in superset - using deep equality checking.
Order is not taken into account.
Duplicates are ignored.
assert.includeDeepMembers([ {a: 1}, {b: 2}, {c: 3} ], [ {b: 2}, {a: 1}, {b: 2} ], 'include deep members');
.oneOf(inList, list, [message])
Asserts that non-object, non-array value inList appears in the flat array list.
assert.oneOf(1, [ 2, 1 ], 'Not found in list');
.changes(function, object, property)
Asserts that a function changes the value of a property
var obj = { val: 10 };
var fn = function() { obj.val = 22 };
assert.changes(fn, obj, 'val');
.doesNotChange(function, object, property)
Asserts that a function does not changes the value of a property
var obj = { val: 10 };
var fn = function() { console.log('foo'); };
assert.doesNotChange(fn, obj, 'val');
.increases(function, object, property)
Asserts that a function increases an object property
var obj = { val: 10 };
var fn = function() { obj.val = 13 };
assert.increases(fn, obj, 'val');
.doesNotIncrease(function, object, property)
Asserts that a function does not increase object property
var obj = { val: 10 };
var fn = function() { obj.val = 8 };
assert.doesNotIncrease(fn, obj, 'val');
.decreases(function, object, property)
Asserts that a function decreases an object property
var obj = { val: 10 };
var fn = function() { obj.val = 5 };
assert.decreases(fn, obj, 'val');
.doesNotDecrease(function, object, property)
Asserts that a function does not decreases an object property
var obj = { val: 10 };
var fn = function() { obj.val = 15 };
assert.doesNotDecrease(fn, obj, 'val');
.ifError(object)
Asserts if value is not a false value, and throws if it is a true value. This is added to allow for chai to be a drop-in replacement for Node’s assert class.
var err = new Error('I am a custom error');
assert.ifError(err); // Rethrows err!
.isExtensible(object)
Asserts that object is extensible (can have new properties added to it).
assert.isExtensible({});
.isNotExtensible(object)
Asserts that object is not extensible.
var nonExtensibleObject = Object.preventExtensions({});
var sealedObject = Object.seal({});
var frozenObject = Object.freese({});
assert.isNotExtensible(nonExtensibleObject);
assert.isNotExtensible(sealedObject);
assert.isNotExtensible(frozenObject);
.isSealed(object)
Asserts that object is sealed (cannot have new properties added to it
and its existing properties cannot be removed).
var sealedObject = Object.seal({});
var frozenObject = Object.seal({});
assert.isSealed(sealedObject);
assert.isSealed(frozenObject);