Sinon.js Cheatsheet - Spy, Stub, Mock & Fake Timers

Decide by two questions: does the behaviour change, and do you want to hard-code expectations? sinon.spy(obj, "method") wraps the real method but keeps its behaviour and only records calls, which you then read as calledOnce, calledWith(arg1, arg2), returned(value), callCount or args[0] — right for "was this called correctly". sinon.stub(obj, "method") replaces the method with a programmable empty function, discarding the original behaviour, and returns / throws / resolves / rejects decide the outcome — right for cutting a dependency off. sinon.mock(obj) combines both: declare with expects("method") including once / never and arguments, then check everything at once with mock.verify(); it is heavier, so reserve it for dense expectations.

Almost always the classic leak: a test double was never restored, so it leaks into everything after it. The cure shown here is the sandbox — call sinon.createSandbox() in beforeEach, create every double through sandbox.spy / sandbox.stub / sandbox.useFakeTimers, then call sandbox.restore() in afterEach to put back all spies, stubs and the fake clock in one go. The manual equivalent is calling restore() on each spy or stub individually. Fake timers are the usual offender: after clock.tick(1000), a missing clock.restore() leaves every later timing-dependent assertion frozen. Diagnostic rule: if a failing test depends on global state such as Date, setTimeout or a replaced method, go look for a leftover double in the previous test.

Take over setTimeout and setInterval with sinon.useFakeTimers(), then step virtual time with the clock: clock.tick(1000) advances by one second and fires only the callbacks due in that window; clock.runAll() drains every queued timer at once, which is handy when a scheduler loops. Pin the starting point with sinon.useFakeTimers({ now: 1000 }), and restrict the blast radius with sinon.useFakeTimers({ toFake: ["setTimeout", "Date"] }) when only specific APIs should be faked. Always clock.restore() afterwards, or let the sandbox do it. The test then finishes in milliseconds while still asserting real post-callback state.

Prefer resolves and rejects. stub.resolves(value) hands back a resolved Promise and stub.rejects(Error) a rejected one, covering the success and failure paths of an async call far more tersely than writing an async function inside callsFake. Reach for stub.callsFake(fn) only when the replaced method does not return a Promise or when the replacement logic is genuinely multi-step. For legacy callback-style APIs use stub.callsArg(0) to invoke the first supplied argument as the callback. When successive calls must yield different values, configure them by ordinal with stub.onCall(0).returns(value).

First establish which of three things went wrong: the expected call never happened (an expects.never() violation), or it happened the right number of times with the wrong arguments (expects.withArgs(arg) mismatch). For the second case, loosen the matcher to a structural one such as sinon.match({ id: sinon.match.number }) and constrain only the fields that matter. Also verify the received value was not polluted by a leftover test double. If strict expectation checking is not buying you anything, the mock syntax is pure overhead — switch to a spy plus assertions: sinon.assert.called, calledOnce, calledWith, notCalled, callCount(spy, 3) and calledWithExactly. Those failures point at the actual recorded call.