Sinon.JS Assertions for Chai

Sinon–Chai provides a set of custom assertions for using the Sinon.JS spy, stub, and mocking framework with the Chai assertion library. You get all the benefits of Chai with all the powerful tools of Sinon.JS.

Instead of using Sinon.JS's assertions:

sinon.assertCalledWith(mySpy, "foo");

or awkwardly trying to use Chai's should or expect interfaces on spy properties:

mySpy.calledWith("foo").should.be.ok;
expect(mySpy.calledWith("foo")).to.be.ok;

you can say

mySpy.should.have.been.calledWith("foo");

Assertions

All of your favorite Sinon.JS assertions made their way into Sinon–Chai. We show the should syntax here; the expect equivalent is also available.

Sinon.JS property/method	Sinon–Chai assertion
called	spy.should.have.been.called
calledOnce	spy.should.have.been.calledOnce
calledTwice	spy.should.have.been.calledTwice
calledThrice	spy.should.have.been.calledThrice
calledBefore	spy1.should.have.been.calledBefore(spy2)
calledAfter	spy1.should.have.been.calledAfter(spy2)
calledWithNew	spy.should.have.been.calledWithNew
alwaysCalledWithNew	spy.should.always.have.been.calledWithNew
calledOn	spy.should.have.been.calledOn(context)
alwaysCalledOn	spy.should.always.have.been.calledOn(context)
calledWith	spy.should.have.been.calledWith(...args)
alwaysCalledWith	spy.should.always.have.been.calledWith(...args)
calledWithExactly	spy.should.have.been.calledWithExactly(...args)
alwaysCalledWithExactly	spy.should.always.have.been.calledWithExactly(...args)
calledWithMatch	spy.should.have.been.calledWithMatch(...args)
alwaysCalledWithMatch	spy.should.always.have.been.calledWithMatch(...args)
returned	spy.should.have.returned(returnVal)
alwaysReturned	spy.should.have.always.returned(returnVal)
threw	spy.should.have.thrown(errorObjOrErrorTypeStringOrNothing)
alwaysThrew	spy.should.have.always.thrown(errorObjOrErrorTypeStringOrNothing)

For more information on the behavior of each assertion, see the documentation for the corresponding spy methods. These of course work on not only spies, but individual spy calls, stubs, and mocks as well.

Installation and Usage

Node

Do an npm install sinon-chai to get up and running. Then:

var chai = require("chai");
var sinonChai = require("sinon-chai");

chai.use(sinonChai);

You can of course put this code in a common test fixture file; for an example using Mocha, see the Sinon–Chai tests themselves.

AMD

Sinon–Chai supports being used as an AMD module, registering itself anonymously (just like Chai). So, assuming you have configured your loader to map the Chai and Sinon–Chai files to the respective module IDs "chai" and "sinon-chai", you can use them as follows:

define(function (require, exports, module) {
    var chai = require("chai");
    var sinonChai = require("sinon-chai");

    chai.use(sinonChai);
});

<script> tag

If you include Sinon–Chai directly with a <script> tag, after the one for Chai itself, then it will automatically plug in to Chai and be ready for use. Note that you'll want to get the latest browser build of Sinon.JS as well:

<script src="chai.js"></script>
<script src="sinon-chai.js"></script>
<script src="sinon.js"></script>

Ruby on Rails

Thanks to Cymen Vig, there's now a Ruby gem of Sinon–Chai that integrates it with the Rails asset pipeline!