Sinon.JS — Test Spies, Stubs and Mocks for JavaScript

Introduction

Sinon.JS provides standalone test doubles — spies, stubs, and mocks — that work with any JavaScript testing framework. It lets you observe function calls, replace dependencies with controlled behaviors, and verify interaction patterns without coupling your tests to a specific runner. The library has been a cornerstone of the JavaScript testing ecosystem for over a decade, offering a battle-tested API for isolating units under test.

What Sinon.JS Does

• Creates spies that record calls, arguments, return values, and exceptions
• Provides stubs that replace functions with programmed behavior and return values
• Offers mocks that combine stubbing with built-in expectation verification
• Includes fake timers to control setTimeout, setInterval, and Date in tests
• Ships a fake XMLHttpRequest and server for testing browser HTTP code without a network

Architecture Overview

Sinon.JS is a pure JavaScript library with zero runtime dependencies. Spies wrap existing functions using property descriptors, recording every invocation while optionally delegating to the original implementation. Stubs extend spies by replacing the function entirely and exposing a fluent API for defining return values, thrown errors, or call-through behavior. Fake timers replace the global clock functions with a synchronous implementation that you advance manually, enabling deterministic testing of time-dependent code.

Self-Hosting & Configuration

• Install via npm: npm install --save-dev sinon
• Import in test files: const sinon = require('sinon') or import sinon from 'sinon'
• Call sinon.restore() in afterEach hooks to reset all fakes between tests
• Use sandboxes via sinon.createSandbox() for grouped cleanup of related stubs
• Compatible with CommonJS and ES modules; ships TypeScript type definitions

Key Features

• Framework-agnostic — works with Mocha, Jest, AVA, Vitest, or any test runner
• Rich assertion API: calledOnce, calledWith, calledBefore, returned, etc.
• Fake timers for deterministic testing of setTimeout, setInterval, and Date
• Fake XMLHttpRequest server for testing browser HTTP code in isolation
• Sandboxes for automatic cleanup of grouped test doubles

Comparison with Similar Tools

• Jest mocks — built into Jest but tightly coupled to the framework; Sinon works everywhere
• Testdouble.js — simpler API philosophy; Sinon offers more granular control and a wider feature set
• Vitest mocking — framework-native and fast; Sinon adds portability across test runners
• Nock — specializes in HTTP request mocking; Sinon provides general-purpose function-level test doubles
• unittest.mock (Python) — similar concept in Python; Sinon is the JavaScript equivalent with a richer spy API

FAQ

Q: What is the difference between a spy, a stub, and a mock? A: A spy records calls without changing behavior. A stub replaces a function with custom behavior. A mock is a stub with built-in expectations that are verified at the end.

Q: Does Sinon work with ES modules? A: Sinon can stub properties on objects, but ES module named exports are read-only bindings. Use dependency injection or a module loader hook to enable stubbing.

Q: How do I clean up stubs between tests? A: Call sinon.restore() in an afterEach hook, or use a sandbox and call sandbox.restore().

Q: Can Sinon fake timers work with async code? A: Yes. Use clock.tickAsync(ms) to advance the clock and flush pending microtasks and timers in the correct order.

Sources

• https://github.com/sinonjs/sinon
• https://sinonjs.org/releases/latest/