Chai BDD API reference.
BDD
The BDD styles are expect and should. Both use the same chainable language to construct assertions, but they differ in the way an assertion is initially constructed. Check out the Style Guide for a comparison.
API Reference
Language Chains
The following are provided as chainable getters to improve the readability of your assertions. They do not provide testing capabilities unless they have been overwritten by a plugin.
Chains
- to
- be
- been
- is
- that
- and
- has
- have
- with
- at
- of
- same
.not
Negates any of assertions following in the chain.
expect(foo).to.not.equal('bar');
expect(goodFn).to.not.throw(Error);
expect({ foo: 'baz' }).to.have.property('foo')
.and.not.equal('bar');.deep
Sets the deep flag, later used by the equal and property assertions.
expect(foo).to.deep.equal({ bar: 'baz' });
expect({ foo: { bar: { baz: 'quux' } } })
.to.have.deep.property('foo.bar.baz', 'quux');.a(type)
The a and an assertions are aliases that can be used either as language chains or to assert a value's type.
// typeof
expect('test').to.be.a('string');
expect({ foo: 'bar' }).to.be.an('object');
expect(null).to.be.a('null');
expect(undefined).to.be.an('undefined');
// language chain
expect(foo).to.be.an.instanceof(Foo);.include(value)
The include and contain assertions can be used as either property based language chains or as methods to assert the inclusion of an object in an array or a substring in a string. When used as language chains, they toggle the contain flag for the keys assertion.
expect([1,2,3]).to.include(2);
expect('foobar').to.contain('foo');
expect({ foo: 'bar', hello: 'universe' }).to.include.keys('foo');.ok
Asserts that the target is truthy.
expect('everthing').to.be.ok;
expect(1).to.be.ok;
expect(false).to.not.be.ok;
expect(undefined).to.not.be.ok;
expect(null).to.not.be.ok;.true
Asserts that the target is true.
expect(true).to.be.true;
expect(1).to.not.be.true;.false
Asserts that the target is false.
expect(false).to.be.false;
expect(0).to.not.be.false;.null
Asserts that the target is null.
expect(null).to.be.null;
expect(undefined).not.to.be.null;.undefined
Asserts that the target is undefined.
expect(undefined).to.be.undefined;
expect(null).to.not.be.undefined;.exist
Asserts that the target is neither null nor undefined.
var foo = 'hi'
, bar = null
, baz;
expect(foo).to.exist;
expect(bar).to.not.exist;
expect(baz).to.not.exist;.empty
Asserts that the target's length is 0. For arrays, it checks the length property. For objects, it gets the count of enumerable keys.
expect([]).to.be.empty;
expect('').to.be.empty;
expect({}).to.be.empty;.arguments
Asserts that the target is an arguments object.
function test () {
expect(arguments).to.be.arguments;
}.equal(value)
Asserts that the target is strictly equal (===) to value. Alternately, if the deep flag is set, asserts that the target is deeply equal to value.
expect('hello').to.equal('hello');
expect(42).to.equal(42);
expect(1).to.not.equal(true);
expect({ foo: 'bar' }).to.not.equal({ foo: 'bar' });
expect({ foo: 'bar' }).to.deep.equal({ foo: 'bar' });.eql(value)
Asserts that the target is deeply equal to value.
expect({ foo: 'bar' }).to.eql({ foo: 'bar' });
expect([ 1, 2, 3 ]).to.eql([ 1, 2, 3 ]);.above(value)
Asserts that the target is greater than value.
expect(10).to.be.above(5);Can also be used in conjunction with length to assert a minimum length. The benefit being a more informative error message than if the length was supplied directly.
expect('foo').to.have.length.above(2);
expect([ 1, 2, 3 ]).to.have.length.above(2);.least(value)
Asserts that the target is greater than or equal to value.
expect(10).to.be.at.least(10);Can also be used in conjunction with length to assert a minimum length. The benefit being a more informative error message than if the length was supplied directly.
expect('foo').to.have.length.of.at.least(2);
expect([ 1, 2, 3 ]).to.have.length.of.at.least(3);.below(value)
Asserts that the target is less than value.
expect(5).to.be.below(10);Can also be used in conjunction with length to assert a maximum length. The benefit being a more informative error message than if the length was supplied directly.
expect('foo').to.have.length.below(4);
expect([ 1, 2, 3 ]).to.have.length.below(4);.most(value)
Asserts that the target is less than or equal to value.
expect(5).to.be.at.most(5);Can also be used in conjunction with length to assert a maximum length. The benefit being a more informative error message than if the length was supplied directly.
expect('foo').to.have.length.of.at.most(4);
expect([ 1, 2, 3 ]).to.have.length.of.at.most(3);.within(start, finish)
Asserts that the target is within a range.
expect(7).to.be.within(5,10);Can also be used in conjunction with length to assert a length range. The benefit being a more informative error message than if the length was supplied directly.
expect('foo').to.have.length.within(2,4);
expect([ 1, 2, 3 ]).to.have.length.within(2,4);.instanceof(constructor)
Asserts that the target is an instance of constructor.
var Tea = function (name) { this.name = name; }
, Chai = new Tea('chai');
expect(Chai).to.be.an.instanceof(Tea);
expect([ 1, 2, 3 ]).to.be.instanceof(Array);.property(name, [value])
Asserts that the target has a property name, optionally asserting that the value of that property is strictly equal tovalue. If the deep flag is set, you can use dot- and bracket-notation for deep references into objects and arrays.
// simple referencing
var obj = { foo: 'bar' };
expect(obj).to.have.property('foo');
expect(obj).to.have.property('foo', 'bar');
// deep referencing
var deepObj = {
green: { tea: 'matcha' }
, teas: [ 'chai', 'matcha', { tea: 'konacha' } ]
};
expect(deepObj).to.have.deep.property('green.tea', 'matcha');
expect(deepObj).to.have.deep.property('teas[1]', 'matcha');
expect(deepObj).to.have.deep.property('teas[2].tea', 'konacha');You can also use an array as the starting point of a deep.property assertion, or traverse nested arrays.
var arr = [
[ 'chai', 'matcha', 'konacha' ]
, [ { tea: 'chai' }
, { tea: 'matcha' }
, { tea: 'konacha' } ]
];
expect(arr).to.have.deep.property('[0][1]', 'matcha');
expect(arr).to.have.deep.property('[1][2].tea', 'konacha');Furthermore, property changes the subject of the assertion to be the value of that property from the original object. This permits for further chainable assertions on that property.
expect(obj).to.have.property('foo')
.that.is.a('string');
expect(deepObj).to.have.property('green')
.that.is.an('object')
.that.deep.equals({ tea: 'matcha' });
expect(deepObj).to.have.property('teas')
.that.is.an('array')
.with.deep.property('[2]')
.that.deep.equals({ tea: 'konacha' });.ownProperty(name)
Asserts that the target has an own property name.
expect('test').to.have.ownProperty('length');.length(value)
Asserts that the target's length property has the expected value.
expect([ 1, 2, 3]).to.have.length(3);
expect('foobar').to.have.length(6);Can also be used as a chain precursor to a value comparison for the length property.
expect('foo').to.have.length.above(2);
expect([ 1, 2, 3 ]).to.have.length.above(2);
expect('foo').to.have.length.below(4);
expect([ 1, 2, 3 ]).to.have.length.below(4);
expect('foo').to.have.length.within(2,4);
expect([ 1, 2, 3 ]).to.have.length.within(2,4);.match(regexp)
Asserts that the target matches a regular expression.
expect('foobar').to.match(/^foo/);.string(string)
Asserts that the string target contains another string.
expect('foobar').to.have.string('bar');.keys(key1, [key2], [...])
Asserts that the target has exactly the given keys, or asserts the inclusion of some keys when using the include orcontain modifiers.
expect({ foo: 1, bar: 2 }).to.have.keys(['foo', 'bar']);
expect({ foo: 1, bar: 2, baz: 3 }).to.contain.keys('foo', 'bar');.throw(constructor)
Asserts that the function target will throw a specific error, or specific type of error (as determined usinginstanceof), optionally with a RegExp or string inclusion test for the error's message.
var err = new ReferenceError('This is a bad function.');
var fn = function () { throw err; }
expect(fn).to.throw(ReferenceError);
expect(fn).to.throw(Error);
expect(fn).to.throw(/bad function/);
expect(fn).to.not.throw('good function');
expect(fn).to.throw(ReferenceError, /bad function/);
expect(fn).to.throw(err);
expect(fn).to.not.throw(new RangeError('Out of range.'));Please note that when a throw expectation is negated, it will check each parameter independently, starting with error constructor type. The appropriate way to check for the existence of a type of error but for a message that does not match is to use and.
expect(fn).to.throw(ReferenceError)
.and.not.throw(/good function/);.respondTo(method)
Asserts that the object or class target will respond to a method.
Klass.prototype.bar = function(){};
expect(Klass).to.respondTo('bar');
expect(obj).to.respondTo('bar');To check if a constructor will respond to a static function, set the itself flag.
Klass.baz = function(){};
expect(Klass).itself.to.respondTo('baz');.itself
Sets the itself flag, later used by the respondTo assertion.
function Foo() {}
Foo.bar = function() {}
Foo.prototype.baz = function() {}
expect(Foo).itself.to.respondTo('bar');
expect(Foo).itself.not.to.respondTo('baz');.satisfy(method)
Asserts that the target passes a given truth test.
expect(1).to.satisfy(function(num) { return num > 0; });.closeTo(expected, delta)
Asserts that the target is equal expected, to within a +/- delta range.
expect(1.5).to.be.closeTo(1, 0.5);.members(set)
Asserts that the target is a superset of set, or that the target and set have the same strictly-equal (===) members. Alternately, if the deep flag is set, set members are compared for deep equality.
expect([1, 2, 3]).to.include.members([3, 2]);
expect([1, 2, 3]).to.not.include.members([3, 2, 8]);
expect([4, 2]).to.have.members([2, 4]);
expect([5, 2]).to.not.have.members([5, 2, 1]);
expect([{ id: 1 }]).to.deep.include.members([{ id: 1 }]);
