Sinon.JS Documentation

Sinon provides a wide range of matchers to allow for flexible argument matching in assertions and stubs. Instead of matching exact values, you can use matchers to verify types, specific properties, or custom logic.

Available matcher categories include:

• Types: any, bool, date, number, string, symbol, typeOf, instanceOf.
• Values & Logic: defined, falsy, truthy, same, match (regex/string).
• Collections: array, object, every, some, map.
• Property/Key Checks: has, hasOwn, hasNested, in, set.

A common anti-pattern is using mocks to verify how a piece of code works (e.g., specific SQL queries). Instead, use fakes to verify what the code does (the resulting behavior). This makes tests resilient to internal refactoring.

// Good: Testing behavior (WHAT the code does)
const fake = sinon.fake.resolves({ user: userData, posts: postsData });
sinon.replace(database, "getUserWithPosts", fake);

const result = await controller.getUserWithPosts(userId);

assert.deepEqual(result.user, expectedUser);
assert.deepEqual(result.posts, expectedPosts);
assert.ok(fake.calledWith(userId));

To write maintainable and debuggable tests with Sinon mocks, follow these guidelines:

1. One mock per test: Multiple mocks make failures difficult to diagnose.
2. Verify once: Call verify() only once, typically in a cleanup block like afterEach.
3. Expect only what matters: Avoid mocking every interaction; only mock what you actually need to verify.
4. Use explicit assertions: For simpler needs, consider using sinon.fake and standard assertions instead of full mocks.
5. Test behavior, not implementation: Avoid coupling tests to internal/private method calls. Use sinon.replace with fakes to test public behavior instead.

Mocks are fake methods that combine the capabilities of spies (tracking calls) and stubs (pre-programmed behavior) with pre-programmed expectations. A mock will automatically fail your test if it is not used exactly as expected.

Best Practices

• Use mocks for the method under test: In a unit test, you should ideally have only one unit under test. Mocks should be used to control how that unit is being used.
• Declare expectations upfront: Use mocks when you want to state expectations before the action occurs, rather than asserting after the fact.
• Avoid overusing mocks: Mocks enforce implementation details. If you wouldn't write a specific assertion for a call, do not mock it; use a stub instead.
• Limit mock count: As a rule of thumb, a single test should contain no more than one mock (even if that mock has multiple expectations).

Use a stub to prevent a specific method from being called directly, which is useful for methods that trigger undesired side effects like fs.readFile. You can use .callsFake() to provide a controlled implementation (e.g., returning a resolved Promise) instead of the real implementation.

import * as sinon from "sinon";
import * as fs from "fs";

// stub out the readFile method
sinon.stub(fs, "readFile").callsFake(function () {
  // and make it return the value we want for our test
  return Promise.resolve("Apple pie");
});

const fileContent = await fs.readFile("somefile");
console.log(fileContent);
// => Apple pie

When using stubs to replace an existing object method, sinon.stub(obj, 'method') combines creation and replacement. When using fakes, you must separate these steps: first create the fake, then use sinon.replace() to inject it into the object.

const obj = {
  method() {
    return "original";
  }
};

// Create the fake separately
const fake = sinon.fake.returns("stubbed");

// Use sinon.replace to plug it in
sinon.replace(obj, "method", fake);

obj.method(); // 'stubbed'

To migrate simple stubs, replace the sinon.stub() chain with the corresponding sinon.fake factory method: