Sinon.JS: Isolate and Inspect Code for Unit Tests

Why it exists

Unit tests should be fast, deterministic, and focused on a single piece of logic. Real-world code has dependencies—network requests, database calls, timers—that are slow and unpredictable. Sinon.JS exists to break these dependencies during testing, allowing you to test your logic in isolation.

The mental model

Think of Sinon.JS as a toolkit for creating "stunt doubles" for parts of your application. Instead of calling a real, unpredictable function (like an API), your test calls a predictable fake that you control. You can tell this fake what to return, and after the test, you can ask it questions like "Were you called?" and "What arguments did you receive?".

How it works

Sinon provides several types of test doubles. A "fake" is a function replacement that records how it was used (call count, arguments). A "stub" is a fake with pre-programmed behavior, like returning a specific value. A "spy" wraps an existing function to record its usage without changing its behavior. It also offers a fake timer API to control time-based functions like setTimeout instantly. You typically set up these doubles before a test and clean them up afterward using sinon.restore().

When to use it

Use Sinon when you need to isolate your code from external or non-deterministic dependencies. Three key places are: first, faking network requests to avoid hitting a real server; second, controlling time with sinon.useFakeTimers() to test debounce or setTimeout logic instantly; third, ensuring a callback function is called correctly by a higher-order function.

When not to use it

Avoid using Sinon for integration tests, where the goal is to verify that multiple components work together correctly. Overusing stubs can also lead to brittle tests that are tightly coupled to implementation details. If you find yourself faking every single function call within the unit you're testing, you might be testing an implementation detail, not a behavior.

One canonical example

A classic use case is testing a function that makes a network call without actually hitting the network. To test a function getTodos(id, callback) that uses jQuery.ajax, you can replace the ajax method with a Sinon fake. First, you replace the method: sinon.replace(jQuery, "ajax", sinon.fake()). Then you call your function: getTodos(42, sinon.fake()). Finally, you can assert that the fake was called as expected: assert(jQuery.ajax.calledWithMatch({ url: "/todo/42/items" })). After the test, you must call sinon.restore() to put the original function back.