Sinon-Chai: Sinon.JS Assertions for Chai

Common errors

• TypeError: Cannot read properties of undefined (reading 'should') OR TypeError: expect is not a function

  cause Chai's assertion interfaces (`should` or `expect`) are not correctly loaded or activated before using Sinon-Chai assertions.
  fix Ensure you have `import { expect, use } from 'chai';` and `use(sinonChai);` at the top of your test file. For the `should` style, also include `import 'chai/register-should';` or call `chai.should();`.

• AssertionError: Expected spy to be called once, but it was not. (or similar for `calledWith`, `returned`, etc.)

  cause The Sinon spy, stub, or mock was either not invoked, called with different arguments, or the test subject did not behave as expected.
  fix Review your test setup and the code under test. Ensure the spy is correctly injected and that the execution path actually triggers the spy. Use `mySpy.getCalls()` or `console.log(mySpy.args)` to inspect the spy's behavior.

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/sinon-chai/index.js from ... is not supported.

  cause You are attempting to import `sinon-chai` using CommonJS `require()` syntax in a project configured for ESM, or Node.js's module resolution is treating it as an ESM module when your code is CJS.
  fix Use ESM import syntax: `import sinonChai from 'sinon-chai';`. If your project is CommonJS, you might need to ensure compatibility or check for older versions that explicitly supported CJS without such issues.

Warnings

• breaking Version 3.0.0 introduced breaking changes, requiring Node.js 4+, Sinon 4+, and Chai 4+.
  Fix: Ensure your project meets the minimum peer dependency requirements for Node.js, Sinon, and Chai before upgrading to `sinon-chai@3.0.0` or higher.
• breaking Version 4.0.0 added support for Chai v5, and 4.0.1 added support for Chai v6. Ensure your Chai version is compatible with your `sinon-chai` version based on the peer dependencies.
  Fix: Check your `package.json` for `chai` and `sinon` versions. `sinon-chai@4.0.x` requires `chai: ^5.0.0 || ^6.0.0` and `sinon: >=4.0.0`.
• gotcha When using `always` assertions (e.g., `alwaysCalledWith`), the `.always` property must be placed directly after `should` or `to` (e.g., `spy.should.always.have.been.calledWith`). Incorrect placement like `spy.should.have.been.alwaysCalledWith` will not work.
  Fix: Adjust your assertion syntax to `expect(spy).to.always.have.been.calledWith(...)` or `spy.should.always.have.been.calledWith(...)`.
• gotcha Sinon-Chai does not directly provide assertions for `Sinon.assert.match`. If you need to assert against complex argument matching, consider using `chai-samsam` or manual checks.
  Fix: For assertions involving `sinon.match`, integrate `chai-samsam` or perform a direct check on the spy's calls like `expect(mySpy.firstCall.args[0]).to.match(someRegex);`.

Install

• npm install sinon-chai npm
• yarn add sinon-chai yarn
• pnpm add sinon-chai pnpm

Imports

• sinonChai
  wrong:

  const sinonChai = require('sinon-chai');

  correct:

  import sinonChai from 'sinon-chai';

  Since v4.0.1, the documentation encourages ESM imports. While CJS might still work, ESM is the recommended approach for modern projects. The default export is the plugin function itself.
• use (Chai method)
  wrong:

  chai.use(sinonChai); // if `chai` itself is imported via CJS `require`

  correct:

  import { use, expect } from 'chai';
  use(sinonChai);

  The Sinon-Chai plugin is activated by passing it to Chai's `use` method. This needs to happen once at the start of your test suite.
• should (Chai style)

  import 'chai/register-should'; // or `chai.should()`
  // ... then later:
  mySpy.should.have.been.calledOnce;

  To use the `should` assertion style, you must either import `chai/register-should` or call `chai.should()` once. This is a Chai-specific setup, not directly tied to sinon-chai, but crucial for its usage with `should`.

Quickstart

This quickstart demonstrates how to set up Sinon-Chai with Chai and Sinon, creating a spy and using `expect` assertions to verify call counts and arguments.

import { expect, use } from 'chai';
import * as sinon from 'sinon';
import sinonChai from 'sinon-chai';

// Initialize Chai with sinon-chai plugin
use(sinonChai);

describe('MyService with Sinon-Chai', () => {
  let mySpy: sinon.SinonSpy;

  beforeEach(() => {
    // Create a new Sinon spy before each test
    mySpy = sinon.spy();
  });

  afterEach(() => {
    // Restore the spy after each test to prevent side effects
    mySpy.restore();
  });

  it('should call the spy once with the expected argument', () => {
    const serviceMethod = (param: string) => {
      mySpy(param);
    };

    serviceMethod('first-call');

    // Use sinon-chai assertions
    expect(mySpy).to.have.been.calledOnce;
    expect(mySpy).to.have.been.calledWith('first-call');
    expect(mySpy).to.not.have.been.calledWith('wrong-argument');
  });

  it('should not call the spy if a condition is not met', () => {
    const serviceMethodConditional = (shouldExecute: boolean) => {
      if (shouldExecute) {
        mySpy('executed');
      }
    };

    serviceMethodConditional(false);

    expect(mySpy).to.not.have.been.called;
    expect(mySpy).to.have.callCount(0);
  });
});