Sinon for JavaScript (Node.js): Complete Guide with Examples

1. What Is Sinon and Why Use It

Sinon.js is a powerful JavaScript library that provides standalone test doubles: spies, stubs, and mocks. It works independently of any specific testing framework (Mocha, Jest, Jasmine, etc.) and integrates seamlessly with all of them. Sinon's core purpose is to isolate your code under test from external dependencies (databases, APIs, file systems, timers), allowing you to verify function behavior in a controlled environment.

Why is this important? In real-world applications, functions often call other functions, interact with external services, or handle asynchronous operations. Without Sinon, it's difficult to verify whether a callback was invoked, with what arguments, how many times, or to simulate a server response. Sinon solves these challenges elegantly, making your tests fast, reliable, and predictable.

The library is especially popular in the Node.js ecosystem, where unit testing is critical. It lets you test functions without making real HTTP requests, accessing databases, or waiting for timers. This speeds up test execution by orders of magnitude and ensures deterministic results.

2. Installation

Install Sinon via npm. For Node.js, run:

npm install sinon --save-dev

If you're using TypeScript, also install the type definitions:

npm install sinon @types/sinon --save-dev

For browser usage, you can include the CDN version:

<script src="https://cdn.jsdelivr.net/npm/sinon@latest/pkg/sinon.js"></script>

After installation, import the library in your test file:

const sinon = require('sinon'); // CommonJS
// or
import sinon from 'sinon'; // ES Modules

3. Quick Start — Minimal Working Example

Let's look at a simple example: a function that calls a callback with a greeting. We want to verify the callback was invoked with the correct argument.

const sinon = require('sinon');

// Function under test
function greet(name, callback) {
  callback(`Hello, ${name}!`);
}

// Test using a spy
const callbackSpy = sinon.spy();
greet('Alice', callbackSpy);

console.log(callbackSpy.calledOnce);    // true
console.log(callbackSpy.calledWith('Hello, Alice!')); // true

This example demonstrates the core idea: we create a spy, pass it to the function under test, then verify how it was called. In real tests, you'll use assertions from your testing framework.

4. Core Methods/Functions/Classes

4.1. `sinon.spy()` — Spy

Signature: sinon.spy([object], [method]) or sinon.spy([func])

What it does: Creates a spy that records information about function calls: call count, arguments, context, return value. It can wrap an existing function or replace an object's method.

Example:

const user = {
  setName: function(name) { this.name = name; }
};

const spy = sinon.spy(user, 'setName');
user.setName('John');

console.log(spy.calledOnce);      // true
console.log(spy.calledWith('John')); // true
console.log(spy.firstCall.args);  // ['John']

spy.restore(); // always restore the original method