Sandboxes

Sandboxes simplify working with fakes that need to be restored and/or verified.

If you’re using fake timers, fake XHR, or you are stubbing/spying on globally accessible properties you should use a sandbox to ease cleanup. By default the spy, stub and mock properties of the sandbox is bound to whatever object the function is run on, so if you don’t want to manually restore(), you have to use this.spy() instead of sinon.spy() (and stub, mock).

"test using sinon.test sandbox": sinon.test(function () {
    var myAPI = { method: function () {} };
    this.mock(myAPI).expects("method").once();

    PubSub.subscribe("message", myAPI.method);
    PubSub.publishSync("message", undefined);
})

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. Usually, this is set by sinon.test such that it is the this value in a given test function.

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:

sinon.config = {
    useFakeServer: sinon.fakeServerWithClock
};

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().

Access requests through sandbox.requests.

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.verify();

Verifies all mocks created through the sandbox.

sandbox.verifyAndRestore();

Verifies all mocks and restores all fakes created through the sandbox.

Test methods

Note: In [email protected] this has been extracted into a separate sinon-test module.

Wrapping test methods in sinon.test allows Sinon.JS to automatically create and manage sandboxes for you. The function’s behavior can be configured through sinon.config.

var wrappedFn = sinon.test(fn);`

The wrappedFn function works exactly like the original one in all respects - in addition a sandbox object is created and automatically restored when the function finishes a call.

By default the spy, stub and mock properties of the sandbox is bound to whatever object the function is run on, so you can do this.spy() (and stub, mock) and it works exactly like sandbox.spy() (and stub, mock), except you don’t need to manually restore().

{
    injectIntoThis: true,
    injectInto: null,
    properties: ["spy", "stub", "mock", "clock", "server", "requests"],
    useFakeTimers: true,
    useFakeServer: true
}

Simply set sinon.config to override any or all of these, e.g.:

sinon.config = {
    useFakeTimers: false,
    useFakeServer: false
}

In this case, defaults are used for the non-existent properties. Additionally, sandboxes and tests will not have automatic access to the fake timers and fake server when using this configuration.

sinon.config

The configuration controls how Sinon binds properties when using sinon.test.

The default configuration looks like:

Boolean injectIntoThis

Causes properties to be injected into the `this` object of the test function. Default true.

Object injectInto

Object to bind properties to. If this is null (default) and injectIntoThis is false (not default), the properties are passed as arguments to the test function instead.

Array properties

Properties to expose. Default is all: ["spy", "stub", "mock", "clock", "server", "requests"]. However, the last three properties are only bound if the following two configuration options are true (which is the default).

Boolean useFakeTimers

Causes timers to be faked and allows clock property to be exposed. Default is true.

Boolean useFakeServer

Causes fake XHR and server to be created and allows server and requests properties to be exposed. Default is true.

Test cases

If you need the behavior of sinon.test for more than one test method in a test case, you can use sinon.testCase, which behaves exactly like wrapping each test in sinon.test with one exception: setUp and tearDown can share fakes.

var obj = sinon.testCase({});