sinon-chai

library4.0.1jsnpmunverified

Sinon-Chai is a testing utility that integrates the Sinon.JS mocking framework with the Chai assertion library, allowing developers to write more expressive and readable assertions for spies, stubs, and mocks. Instead of using Sinon's direct assertion methods (`sinon.assert.calledWith`) or awkward Chai property checks, Sinon-Chai extends Chai's `should` and `expect` interfaces to provide natural language assertions like `expect(mySpy).to.have.been.calledWith('foo')`. The current stable version is 4.0.1, which supports Chai v5 and v6, and Sinon v4+. The library maintains an active release cadence, typically updating to support new major versions of its peer dependencies, Chai and Sinon. Key differentiators include its seamless integration into the Chai assertion chain, improving test readability and developer experience by providing a unified assertion style across a test suite. It's widely used in JavaScript testing environments for both Node.js and browser applications.

testing

npm install sinon-chai

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SINON-CHAI

sinon-chai

testingjavascriptv4.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

sinonChai

✓ import sinonChai from 'sinon-chai';

✗ const sinonChai = require('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)

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

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

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`.

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); }); });

Debug

Known issues

breakingVersion 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.

affects: >=3.0.0

breakingVersion 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`.

affects: >=4.0.0

gotchaWhen 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(...)`.

affects: >=3.0.0

gotchaSinon-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);`.

affects: >=3.0.0

Errors

Common errors & fixes

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

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.)

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.

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.

Upgrade

Version history

4.0.1latest on npm

Audit

Dependencies

chairequiredPeer dependency, Sinon-Chai extends Chai's assertion interface.

sinonrequiredPeer dependency, Sinon-Chai provides assertions for Sinon's spies, stubs, and mocks.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/chaijs/sinon-chai ↗

packagehttps://www.npmjs.com/package/sinon-chai ↗

homepagehttps://www.chaijs.com/plugins/sinon-chai ↗