Sinon Cheatsheet - Test Doubles

This reference is for JavaScript developers writing unit tests who need to isolate the code under test from its surroundings. It covers spies for observing calls, stubs to replace behavior with return/throw/resolve constants, strict mocks with expectations, fake timers to fast-forward setTimeout, and sandboxes that auto-restore everything. Later sections show the sinon.assert helpers and practical patterns like sinon.replace and parameter matchers. After reading you should be able to spy on a dependency, stub an external call, control time in tests, and clean up all doubles in a teardown.

Languages·46 commands·Last updated 2026-07-21

Spy 8

sinon.spy(obj, "method")

Spy on an object's method calls

sinon.spy(fn)

Wrap a function as a spy

spy.calledOnce

Whether called exactly once

spy.calledWith(arg1, arg2)

Whether called with specific args

spy.returned(value)

Whether returned a value

spy.callCount

Get the call count

spy.args[0]

Get the first call's args array

spy.restore()

Restore the original method

Stub 9

sinon.stub(obj, "method")

Replace a method with an empty function

stub.returns(value)

Specify a return value

stub.throws(Error)

Throw an exception

stub.callsFake(fn)

Replace with a custom function

stub.resolves(value)

Return a resolved Promise (async)

stub.rejects(Error)

Return a rejected Promise (async)

stub.callsArg(0)

Call the first arg as a callback

stub.onCall(0).returns(value)

Return different values per call

stub.restore()

Restore the original method

Mock 7

sinon.mock(obj)

Create a mock object

mock.expects("method")

Expect a method to be called

expects.once()

Expect it called once

expects.withArgs(arg)

Expect it called with args

expects.never()

Expect it never called

mock.verify()

Verify all expectations

mock.restore()

Restore and clear all expectations

Fake Timers 6

sinon.useFakeTimers()

Take over setTimeout/setInterval

clock.tick(1000)

Advance 1000ms

clock.runAll()

Run all queued timers

clock.restore()

Restore real time

sinon.useFakeTimers({ now: 1000 })

Set an initial time

sinon.useFakeTimers({ toFake: ["setTimeout", "Date"] })

Fake only specified APIs

Assertions & Verification 6

sinon.assert.called(spy)

Assert a spy was called

sinon.assert.calledOnce(spy)

Assert called once

sinon.assert.calledWith(spy, arg)

Assert called with args

sinon.assert.notCalled(spy)

Assert not called

sinon.assert.callCount(spy, 3)

Assert call count

sinon.assert.calledWithExactly(spy, arg)

Assert exact argument match

Sandbox 5

sinon.createSandbox()

Create an isolated sandbox (recommended in beforeEach)

sandbox.spy(obj, "method")

Create a spy inside the sandbox

sandbox.stub(obj, "method")

Create a stub inside the sandbox

sandbox.useFakeTimers()

Use fake timers inside the sandbox

sandbox.restore()

Restore everything in the sandbox at once

Useful Patterns 5

sinon.replace(obj, "method", fn)

Replace a method (preferred over direct stub)

sinon.replaceGetter(obj, "prop", fn)

Replace an object getter

sinon.replaceSetter(obj, "prop", fn)

Replace an object setter

sinon.fake()

Create a no-op fake function

sinon.match({ id: sinon.match.number })

Argument matcher (type/shape match)

Tips

Spy watches calls without changing behavior; Stub replaces behavior; Mock combines both and verifies expectations.
Always restore() after tests, or use a sandbox to manage automatically (call sandbox.restore in afterEach).
Fake Timers test scheduled tasks without real waits; remember to restore after tick.
sinon.assert throws errors, suited for test frameworks; you can also read spy properties directly.
stub.resolves/rejects handle Promises more concisely than callsFake-wrapped async functions.

Official References

Each command links to its official documentation below, so you can verify the latest usage and read deeper.

MDN JavaScript Docs

Maintained by LaoHand

Publicly updated on Jul 21, 2026, continuously proofread against official docs.

Contact Us

Wrong command or description? Send us corrections, business inquiries or product feedback by email.