The BDD style is exposed through expect or should interfaces. In both scenarios, you chain together natural language assertions.

// expect
var expect = require('chai').expect;
expect(foo).to.equal('bar');

// should
var should = require('chai').should();
foo.should.equal('bar');

Differences

The expect interface provides a function as a starting point for chaining your language assertions. It works on node.js and in all browsers.

The should interface extends Object.prototype to provide a single getter as the starting point for your language assertions. It works on node.js and in all browsers except Internet Explorer.

Configuration

By default, Chai does not show stack traces upon an AssertionError. This can be changed by modifying the includeStack parameter for chai.Assertion. For example:

var chai = require('chai');
chai.Assertion.includeStack = true; // defaults to false

Should Extras

Lorem ipsum

Language Guide

Language Chains

The following are provide as chainable getters to improve the readability of your assertions. They do not provide an testing capability unless they have been overwritten by a plugin.

Chains

  • to
  • be
  • been
  • is
  • and
  • have
  • with

.not

Negates any of assertions following in the chain.

.a(type)

  • @param{ String }type

Assert typeof. Also can be used as a language chain.

 expect('test').to.be.a('string');
 expect(foo).to.be.an.instanceof(Foo);

.include(value)

  • @param{ Object | String | Number }obj

Assert the inclusion of an object in an Array or substring in string. Also toggles the contain flag for the keys assertion if used as property.

expect([1,2,3]).to.include(2);
expect('foobar').to.contain('foo');
expect({ foo: 'bar', hello: 'universe' }).to.include.keys('foo');

.ok

Assert object truthiness.

 expect('everthing').to.be.ok;
 expect(false).to.not.be.ok;
 expect(undefined).to.not.be.ok;
 expect(null).to.not.be.ok;

.true

Assert object is true

.false

Assert object is false

.null

Assert object is null

.undefined

Assert object is undefined

.exist

Assert object exists (null).

 var foo = 'hi'
   , bar;
 expect(foo).to.exist;
 expect(bar).to.not.exist;

.empty

Assert object's length to be 0.

 expect([]).to.be.empty;

.arguments

Assert object is an instanceof arguments.

 function test () {
   expect(arguments).to.be.arguments;
 }

.equal(value)

  • @param{ Mixed }value

Assert strict equality.

 expect('hello').to.equal('hello');

.eql(value)

  • @param{ * }value

Assert deep equality.

 expect({ foo: 'bar' }).to.eql({ foo: 'bar' });

.above(value)

  • @param{ Number }value

Assert greater than value.

 expect(10).to.be.above(5);

.below(value)

  • @param{ Number }value

Assert less than value.

 expect(5).to.be.below(10);

.within(start, finish)

  • @param{ Number }startlowerbound inclusive
  • @param{ Number }finishupperbound inclusive

Assert that a number is within a range.

 expect(7).to.be.within(5,10);

.instanceof(constructor)

  • @param{ Constructor }

Assert instanceof.

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

 expect(Chai).to.be.an.instanceof(Tea);

.property(name, [value])

  • @param{ String }name
  • @param{ Mixed }value(optional)

Assert that property of name exists, optionally with value.

 var obj = { foo: 'bar' }
 expect(obj).to.have.property('foo');
 expect(obj).to.have.property('foo', 'bar');
 expect(obj).to.have.property('foo').to.be.a('string');

.ownProperty(name)

  • @param{ String }name

Assert that has own property by name.

 expect('test').to.have.ownProperty('length');

.length(val)

  • @param{ Number }length

Assert that object has expected length.

 expect([1,2,3]).to.have.length(3);
 expect('foobar').to.have.length(6);

.match(regexp)

  • @param{ RegExp }RegularExpression

Assert that matches regular expression.

 expect('foobar').to.match(/^foo/);

.string(string)

  • @param{ String }string

Assert inclusion of string in string.

 expect('foobar').to.have.string('bar');

.keys(key1, [key2], [...])

  • @param{ String | Array }Keys

Assert exact keys or the inclusing of keys using the contain modifier.

 expect({ foo: 1, bar: 2 }).to.have.keys(['foo', 'bar']);
 expect({ foo: 1, bar: 2, baz: 3 }).to.contain.keys('foo', 'bar');

.throw(constructor)

Assert that a function will throw a specific type of error, or specific type of error (as determined using instanceof), 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)

  • @param{ String }method

Assert that object/class will respond to a method.

 expect(Klass).to.respondTo('bar');
 expect(obj).to.respondTo('bar');

.satisfy(method)

  • @param{ Function }matcher

Assert that passes a truth test.

 expect(1).to.satisfy(function(num) { return num > 0; });

.closeTo(expected, delta)

  • @param{ Number }expected
  • @param{ Number }delta

Assert that actual is equal to +/- delta.

 expect(1.5).to.be.closeTo(1, 0.5);