Sinon.JS Test Spies, Stubs, and Mocks

Common errors

• TypeError: sinon.stub is not a function

  cause This error typically occurs when attempting to destructure `stub` as a named import (e.g., `import { stub } from 'sinon';`) or when `sinon` itself is not correctly imported.
  fix Ensure Sinon is imported as a default export: `import sinon from 'sinon';` (ESM) or `const sinon = require('sinon');` (CommonJS), and then access `stub` as a property: `sinon.stub()`.

• TypeError: Cannot read properties of undefined (reading 'reset') OR console warning: 'spy.reset()' is deprecated. Use 'spy.resetHistory()' instead.

  cause Attempting to use the `spy.reset()` method, which has been deprecated since v4.1.4 and is no longer the recommended way to clear a spy's state.
  fix Replace all calls to `spy.reset()` with `spy.resetHistory()` to clear the call history, arguments, and return values of a spy or stub. Use `spy.restore()` to revert the original method.

• Error: Cannot stub non-existent property 'someMethodName'

  cause Sinon cannot stub a method or property that does not exist on the target object at the moment `sinon.stub()` is called.
  fix Verify that the method or property you intend to stub (`someMethodName`) exists on the object you are passing to `sinon.stub()`. This often happens with dynamic properties or when stubbing properties on prototypes that haven't been correctly inherited or defined.

Warnings

• breaking Sinon v3.0.0 removed several previously deprecated exports. Additionally, `fakeXhr`, `fakeServer`, and `fakeServerWithClock` functionalities were extracted into the `nise` package, though they were re-imported into Sinon's top-level API. Direct access to these modules via their old, internal paths may break.
  Fix: Consult the v3.0.0 migration guide on sinonjs.org for full details. For most users, continue to access functionalities like `sinon.useFakeXMLHttpRequest()` via the top-level `sinon` object.
• deprecated The `spy.reset()` method was deprecated in favor of `spy.resetHistory()` starting from v4.1.4. While `reset()` still works in current versions (21.x.x), it emits a deprecation warning and may be removed in future major releases.
  Fix: Update your code to use `spy.resetHistory()` for clearing call history, arguments, and return values of a spy or stub. Use `spy.restore()` for reverting the original method.
• gotcha Version 4.1.5 contained a bug where `sinon.useFakeServer()` could return an unexpected server type, leading to incorrect test behavior. This issue was promptly addressed in the following patch release.
  Fix: Ensure your project is using Sinon.js v4.1.6 or a later version to avoid issues with `sinon.useFakeServer()`.
• gotcha Failure to call `clock.restore()` after `sinon.useFakeTimers()` can lead to global state pollution, causing unexpected behavior in subsequent tests or other parts of the application that rely on real timer functions or the global `Date` object.
  Fix: Always ensure `clock.restore()` is called in an `afterEach` or `after` hook within your test suite to revert global timers and `Date` to their original implementations.

Install

• npm install sinon npm
• yarn add sinon yarn
• pnpm add sinon pnpm

Imports

• sinon
  wrong:

  const sinon = require('sinon');

  correct:

  import sinon from 'sinon';

  While CommonJS `require` works, ESM `import` is the recommended modern approach. Sinon exports a default object containing all its utilities.
• stub
  wrong:

  import { stub } from 'sinon';

  correct:

  import sinon from 'sinon'; sinon.stub(obj, 'method');

  Sinon's core utilities like `stub`, `spy`, `mock`, `useFakeTimers` are properties of the default `sinon` object, not direct named exports from the package root.
• useFakeTimers

  import sinon from 'sinon'; const clock = sinon.useFakeTimers();

  Access `useFakeTimers` via the default imported `sinon` object. It's crucial to call `clock.restore()` after tests to prevent global state pollution.

Quickstart

Demonstrates stubbing an asynchronous dependency's method and verifying its interaction for isolated unit testing.

import sinon from 'sinon';

// Simulate an external API dependency
class ExternalAPI {
  async getData(): Promise<string> {
    // In a real application, this would make an actual network call
    return Promise.resolve('Real Data From Server');
  }
}

// Our code under test that depends on ExternalAPI
class MyService {
  constructor(private api: ExternalAPI) {}

  async processData(): Promise<string> {
    const data = await this.api.getData();
    return data.toUpperCase();
  }
}

async function runExample() {
  const api = new ExternalAPI();
  const service = new MyService(api);

  // Create a stub for the API's getData method
  const getDataStub = sinon.stub(api, 'getData');

  // Configure the stub to return a predictable, mock value
  getDataStub.resolves('Mocked Data');

  // Call the method under test, which now uses the stubbed getData
  const result = await service.processData();

  console.log('Processed Result:', result); // Expected output: MOCKED DATA
  console.log('getData was called once:', getDataStub.calledOnce); // Expected output: true

  // Restore the original method to clean up after the test
  getDataStub.restore();
}

runExample().catch(console.error);