Sinon.JS: spies, stubs and mocks for JavaScript tests

What Sinon.JS replaces in a JavaScript test suite

Unit tests often need two things a plain assertion library cannot give: a record of how a function was called, and a substitute for a function that is slow, external or nondeterministic. Sinon.JS exists for both. The README describes it as "Standalone and test framework agnostic JavaScript test spies, stubs and mocks", and the package description in package.json is the shorter version: "JavaScript test spies, stubs and mocks."

The project states its goals explicitly. No global pollution. Easy to use. Minimal integration. Easy to embed with any testing framework. Easily fake any interface. Ship with ready-to-use fakes for timers. That list is the clearest statement of who this is for: teams writing JavaScript unit tests who do not want their mocking layer welded to Mocha, Jest or anything else. The same fakes travel with you if the runner changes.

That last goal matters more than it looks. Fake timers are the part people reach for when a test has to wait for a debounce, a retry or a scheduled callback. Sinon bundles them rather than leaving you to wire a separate clock library.

Spies, stubs, mocks and a clock: the mechanism

Sinon.JS is built around three kinds of fake plus a timer fake, and the distinction between them is the design decision worth understanding before you adopt it.

A spy wraps a function and records calls without changing what the function does. A stub replaces the function entirely, so you decide what it returns or throws. A mock combines the replacement with expectations about how it should be called. The README does not spell out these definitions; it points to the project homepage for usage documentation, so the authoritative descriptions live at sinonjs.org rather than in the repository README.

The fourth piece, the clock, follows the same pattern applied to time. The goals list says the library ships "ready-to-use fakes for timers", which means a test can advance or freeze time instead of sleeping. That is the mechanism that makes a test for a timeout finish in milliseconds rather than seconds.

The repository layout reflects the split between build input and output. Source lives in src/, tests in test/, and the README states plainly that lib/ is generated build output and is not committed. If you clone the repository rather than installing the package, you are expected to run the build before the library exists in usable form. That is a real difference from installing from npm, where the artifact is already built.

Installing Sinon.JS and using a stub for the first time

The README gives one installation route: npm. The command is a single line, and after it the package is available to your test files.

npm install sinon

The README also notes that browser builds are available for download from the project homepage, and that npm based CDNs can be used instead. Those are alternatives for projects that do not run a bundler or a Node test process.

Once installed, the smallest useful exercise is a stub that replaces a function and returns a fixed value. The README does not include a usage example, so the exact API surface should be read from the documentation on sinonjs.org. What the package description confirms is the category: test spies, stubs and mocks. A test that stubs a dependency and asserts on the recorded calls is the pattern the library is built for.

If you are working inside the repository itself rather than consuming the package, the README is explicit that lib/ is generated and not committed, and that you should run this to regenerate it:

npm run build

That distinction is worth keeping straight. Consumers install from npm; contributors build from source.

Where Sinon.JS is the wrong tool

The strongest argument against adding Sinon.JS is that many test runners now ship their own fakes. If your framework already provides function replacement, call recording and a timer fake, adding Sinon.JS means a second set of concepts for the same job, and reviewers have to know which one a given test is using. The README's own claim is that Sinon is test framework agnostic, which is a benefit only if you actually value that independence.

There is a second, quieter limitation. The README does not document usage. It says to see the project homepage for documentation and to check the sinon tag on Stack Overflow for questions not covered there. For a library whose API surface is the product, that is a thin repository README, and it means the repository alone is not enough to evaluate the API before you install. You will be reading sinonjs.org either way.

A third boundary is the generated lib/ directory. Anyone who clones the repository and expects to read or patch the shipped code directly will find build output instead, because lib/ is not committed. Debugging a published artifact back to source means going through src/ and the build step, not reading the installed file.

Finally, this is a JavaScript testing library. It does not help you test Python, Go or Rust, and it does not replace an assertion library. It fakes and records; it does not decide whether your values are equal.

Sinon.JS compared with the fakes built into a test runner

The realistic alternative for most teams is not another mocking library but the mocking that already sits inside their runner. A runner with built-in function replacement gives you one dependency, one set of docs, and one mental model. Sinon.JS gives you a fake layer that survives a change of runner.

The difference in approach is where the fakes live. Built-in fakes are part of the runner's lifecycle, so setup and teardown are handled by the runner's own hooks. Sinon.JS is standalone, which the README lists as a goal, and framework agnostic, which means you wire it into whatever hooks your runner provides. That is more explicit and slightly more work per test file, and it is exactly what you want if the suite is shared across runners or if the runner is expected to change.

The timer fake is the other axis. Sinon.JS ships timer fakes as part of the package rather than as a separate install, and the README lists that under goals. If your tests are full of timeouts and scheduled callbacks, that inclusion is a concrete reason to pick it over assembling the same capability from pieces.

One thing the README does not offer is a migration guide from any specific runner's built-in mocks. There is no documented path for converting an existing suite, so a switch is a manual rewrite of the faking layer.

Maintenance, licence and the cost of upgrading

The repository is not archived, and its last push was on 2026-09-10, so the project is being touched recently. That is a statement about the repository, not a promise about release cadence. The release list available here is old and does not reflect the current version: the three most recent entries shown are v4.2.0, v4.2.1 and v4.2.2, all from January 2018, while package.json declares version 22.1.0. Anyone judging the project by that release list alone would draw the wrong conclusion about where it stands.

Upgrade cost is not documented in the README. What is documented is a CHANGES.md file at the repository root, which is where release history would be read, and a RELEASE.md describing the release process. The README also mentions that artifact-first contract tests are used to protect public APIs during migration, and links CONTRIBUTING.md for details. That is a signal about how the maintainers think about breaking changes, but it is not a compatibility guarantee for your code.

On licensing, the README states that Sinon.js was released under BSD-3 and links the LICENSE file, and package.json declares "license": "BSD-3-Clause". The repository metadata shown here records the licence as NOASSERTION, which conflicts with both the README and package.json. If licence terms matter to your organisation, read the LICENSE file in the repository and treat the metadata field as unreliable rather than assuming either answer. This is not legal advice.

Funding is listed in package.json as OpenCollective, with backer and sponsor sections in the README. That is the maintenance model: individual and corporate sponsorship rather than a vendor.

Editorial conclusion

Adopt Sinon.JS when you need to observe calls, replace a function, or fake timers in a test suite that is not tied to one framework. Skip it if your framework already provides the same fakes and you want one dependency fewer. Before committing, check COMPATIBILITY.md for your runtime and read the usage documentation on sinonjs.org, because the README itself only points there.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. sinonjs/sinon on GitHub