Sinon Jest Matchers

Why

TL;DR

Without this library, in case of an error you will get very vague error messages

Before:

1expect(received).toEqual(expected) // deep equality
2
3Expected: 2
4Received: 1

After:

1expect(sinon.spy()).sinonToBeCalledTimes(expected)
2
3Expected number of calls: 2
4Received number of calls: 1

Deeper explanation:

Example: If you want to use sinon spies you will need to do something like this:

1test('Check that spy called', async () => {
2    const mySpy = sinon.spy();
3
4    mySpy();
5    
6    // Triggering an error
7    expect(mySpy.callCount).toEqual(2);
8});

The error message will be:

1expect(received).toEqual(expected) // deep equality
2
3Expected: 2
4Received: 1

However, if you use this library, the test will look like this:

1test('Check that spy called', async () => {
2    const mySpy = sinon.spy();
3
4    mySpy();
5
6    // Triggering an error
7    expect(mySpy).sinonToBeCalledTimes(2);
8});

And the error message will be:

1expect.sinonToBeCalledTimes(expected)
2
3Expected number of calls: 2
4Received number of calls: 1

Installation

With npm:

1npm install --save-dev sinon-jest-matchers

With yarn:

1yarn add -D sinon-jest-matchers

Setup

1// ./testSetup.js
2
3// add all sinon-jest-matchers matchers
4import * as matchers from 'sinon-jest-matchers';
5expect.extend(matchers);
6
7// or just add specific matchers
8import { sinonToBeCalled, sinonToBeCalledTimes } from 'sinon-jest-matchers';
9expect.extend({ sinonToBeCalled, sinonToBeCalledTimes });

Add your setup script to your Jest setupFilesAfterEnv configuration. See for help

1"jest": {
2  "setupFilesAfterEnv": ["./testSetup.js"]
3}

To automatically extend expect with all matchers, you can use

1"jest": {
2  "setupFilesAfterEnv": ["sinon-jest-matchers/all"]
3}

Typescript

If your editor does not recognise the custom sinon-jest-matchers matchers, add a global.d.ts file to your project with:

1import 'sinon-jest-matchers';

Note: When using ts-jest >= 25.5.0

Since the breaking changes in 25.5.0 you may also need to update your tsconfig.json to include the new global.d.ts file in the files property like so:

1{
2  "compilerOptions": {
3    ...
4  },
5  ...
6  "files": ["global.d.ts"]
7}

Also note that when adding this for the first time this affects which files are compiled by the TypeScript compiler and you might need to add the include property as well. See the TypeScript docs for more details.

If the above import syntax does not work, replace it with the following:

1/// <reference types="sinon-jest-matchers" />

Matchers

.sinonToBeCalled()

Equivalent to .toBeCalled() and .toHaveBeenCalled() in jest

1function drinkAll(callback, flavour) {
2  if (flavour !== 'octopus') {
3    callback(flavour);
4  }
5}
6
7describe('drinkAll', () => {
8  test('drinks something lemon-flavoured', () => {
9    const drink = sinon.spy();
10    drinkAll(drink, 'lemon');
11    expect(drink).sinonToBeCalled();
12  });
13
14  test('does not drink something octopus-flavoured', () => {
15    const drink = sinon.spy();
16    drinkAll(drink, 'octopus');
17    expect(drink).not.sinonToBeCalled();
18  });
19});

.sinonToBeCalledTimes(number)

Equivalent to .toHaveBeenCalledTimes(number) and .toBeCalledTimes(number) in jest

1test('drinkEach drinks each drink', () => {
2  const drink = sinon.spy();
3  drinkEach(drink, ['lemon', 'octopus']);
4  expect(drink).sinonToBeCalledTimes(2);
5});

.sinonToBeCalledWith(arg1, arg2, ...)

Equivalent to .toHaveBeenCalledWith(arg1, arg2, ...) and .toBeCalledWith() in jest

1test('registration applies correctly to orange La Croix', () => {
2    const beverage = new LaCroix('orange');
3    register(beverage);
4    const f = sinon.spy();
5    applyToAll(f);
6    expect(f).sinonToBeCalledWith(beverage);
7});

.sinonToBeCalledTimesWith(number, arg1, arg2, ...)

Equivalent combination of .sinonToBeCalledTimes(number) with .sinonToBeCalledWith(arg1, arg2, ...)

1test('registration applies correctly to orange La Croix', () => {
2  const beverage = new LaCroix('orange');
3  register(beverage);
4  const f = sinon.spy();
5  applyToAll(f);
6  applyToAll(() => {});
7  applyToAll(f);
8  expect(f).sinonToBeCalledTimesWith(2, beverage);
9});

.sinonLastCalledWith(arg1, arg2, ...)

Equivalent to .toHaveBeenLastCalledWith(arg1, arg2, ...) and .lastCalledWith(arg1, arg2, ...) in jest

1test('applying to all flavors does mango last', () => {
2  const drink = sinon.spy();
3  applyToAllFlavors(drink);
4  expect(drink).sinonLastCalledWith('mango');
5});

.sinonNthCalledWith(nthCall, arg1, arg2, ....)

Equivalent to .toHaveBeenNthCalledWith(nthCall, arg1, arg2, ...) and .nthCalledWith(nthCall, arg1, arg2, ...) in jest

1test('drinkEach drinks each drink', () => {
2  const drink = sinon.spy();
3  drinkEach(drink, ['lemon', 'octopus']);
4  expect(drink).sinonNthCalledWith(1, 'lemon');
5  expect(drink).sinonNthCalledWith(2, 'octopus');
6});

Note: The nth argument must be positive integer starting from 1.

.sinonToReturn()

Equivalent to .toHaveReturned() and .toReturn() in jest

1test('drinks returns', () => {
2  const drink = sinon.spy(() => true);
3
4  drink();
5
6  expect(drink).sinonToReturn();
7});

.sinonToReturnTimes(number)

Equivalent to .toHaveReturnedTimes(number) and .toReturnTimes(number) in jest

1test('drink returns twice', () => {
2  const drink = sinon.spy(() => true);
3
4  drink();
5  drink();
6
7  expect(drink).sinonToReturnTimes(2);
8});

.sinonToReturnWith(value)

Equivalent to .toHaveReturnedWith(value) and .toReturnWith(value) in jest

1test('drink returns La Croix', () => {
2  const beverage = {name: 'La Croix'};
3  const drink = sinon.spy(beverage => beverage.name);
4
5  drink(beverage);
6
7  expect(drink).sinonToReturnWith('La Croix');
8});

.sinonLastReturnedWith(value)

Equivalent to .toHaveLastReturnedWith(value) and .lastReturnedWith(value) in jest

1test('drink returns La Croix (Orange) last', () => {
2  const beverage1 = {name: 'La Croix (Lemon)'};
3  const beverage2 = {name: 'La Croix (Orange)'};
4  const drink = sinon.spy(beverage => beverage.name);
5
6  drink(beverage1);
7  drink(beverage2);
8
9  expect(drink).sinonLastReturnedWith('La Croix (Orange)');
10});

Inspirations and credits

1. The matchers and their tests taken from jest code and updated to use sinon
2. jest-extended for the loading, setup and the file directory structure
3. The expect API docs are taken from jest website and updated to sinon