Sandboxes

Sandboxes removes the need to keep track of every fake created, which greatly simplifies cleanup.

var sinon = require('sinon');

var myAPI = { myMethod: function () {} };
var sandbox = sinon.sandbox.create();

describe('myAPI.hello method', function () {

    beforeEach(function () {
        // stub out the `hello` method
        sandbox.stub(myApi, 'hello');
    });

    afterEach(function () {
        // completely restore all fakes created through the sandbox
        sandbox.restore();
    });

    it('should be called once', function () {
        myAPI.hello();
        sinon.assert.calledOnce(myAPI.hello);
    });

    it('should be called twice', function () {
        myAPI.hello();
        myAPI.hello();
        sinon.assert.calledTwice(myAPI.hello);
    });
});

Sandbox API

var sandbox = sinon.sandbox.create();

Creates a sandbox object

var sandbox = sinon.sandbox.create(config);

The sinon.sandbox.create(config) method is mostly an integration feature, and as an end-user of Sinon.JS you will probably not need it.

Creates a pre-configured sandbox object. The configuration can instruct the sandbox to include fake timers, fake server, and how to interact with these.

The default configuration looks like:

sinon.defaultConfig = {
    // ...
    injectInto: null,
    properties: ["spy", "stub", "mock", "clock", "server", "requests"],
    useFakeTimers: true,
    useFakeServer: true
}

injectInto

The sandbox's methods can be injected into another object for convenience. The injectInto configuration option can name an object to add properties to.

properties

What properties to inject. Note that simply naming "server" here is not sufficient to have a server property show up in the target object, you also have to set useFakeServer to true.

useFakeTimers

If true, the sandbox will have a clock property. Can also be an Array of timer properties to fake.

useFakeServer

If true, server and requests properties are added to the sandbox. Can also be an object to use for fake server. The default one is sinon.fakeServer, but if you're using jQuery 1.3.x or some other library that does not set the XHR's onreadystatechange handler, you might want to do: ```javascript sinon.config = { useFakeServer: sinon.fakeServerWithClock }; ``` #### `sandbox.assert();` A convenience reference for [`sinon.assert`](./assertions) *Since `[email protected]`* #### `sandbox.spy();` Works exactly like `sinon.spy`, only also adds the returned spy to the internal collection of fakes for easy restoring through `sandbox.restore()` #### `sandbox.stub();` Works almost exactly like `sinon.stub`, only also adds the returned stub to the internal collection of fakes for easy restoring through `sandbox.restore()`. The sandbox `stub` method can also be used to stub any kind of property. This is useful if you need to override an object's property for the duration of a test, and have it restored when the test completes #### `sandbox.mock();` Works exactly like `sinon.mock`, only also adds the returned mock to the internal collection of fakes for easy restoring through `sandbox.restore()` #### `sandbox.useFakeTimers();` Fakes timers and binds the `clock` object to the sandbox such that it too is restored when calling `sandbox.restore()`. Access through `sandbox.clock`. #### `sandbox.useFakeXMLHttpRequest();` Fakes XHR and binds the resulting object to the sandbox such that it too is restored when calling `sandbox.restore()`. Since 2.x, you can no longer access requests through `sandbox.requests` - use `sandbox.useFakeServer` to do this. This function maps to `sinon.useFakeXMLHttpRequest`, only with sandboxing. #### `sandbox.useFakeServer();` Fakes XHR and binds a server object to the sandbox such that it too is restored when calling `sandbox.restore()`. Access requests through `sandbox.requests` and server through `sandbox.server` #### `sandbox.restore();` Restores all fakes created through sandbox. #### `sandbox.reset();` Resets the internal state of all fakes created through sandbox. #### `sandbox.resetBehavior();` Resets the behaviour of all stubs created through the sandbox. *Since `[email protected]`* #### `sandbox.resetHistory();` Resets the history of all stubs created through the sandbox. *Since `[email protected]`* #### `sandbox.verify();` Verifies all mocks created through the sandbox. #### `sandbox.verifyAndRestore();` Verifies all mocks and restores all fakes created through the sandbox.