jest-when

What is jest-when?

The jest-when package is an extension for Jest that allows for more readable and maintainable mock function behavior. It provides a way to define mock implementations based on specific argument conditions, making it easier to set up complex mocks.

What are jest-when's main functionalities?

Mocking based on arguments

This feature allows you to define different return values for a mock function based on the arguments it is called with. This makes it easier to handle multiple scenarios in your tests.

const { when } = require('jest-when');
const mockFn = jest.fn();

when(mockFn).calledWith(1).mockReturnValue('one');
when(mockFn).calledWith(2).mockReturnValue('two');

console.log(mockFn(1)); // 'one'
console.log(mockFn(2)); // 'two'
console.log(mockFn(3)); // undefined

Mocking based on multiple arguments

This feature allows you to define return values for a mock function based on multiple arguments, providing more granular control over the mock behavior.

const { when } = require('jest-when');
const mockFn = jest.fn();

when(mockFn).calledWith(1, 'a').mockReturnValue('one-a');
when(mockFn).calledWith(2, 'b').mockReturnValue('two-b');

console.log(mockFn(1, 'a')); // 'one-a'
console.log(mockFn(2, 'b')); // 'two-b'
console.log(mockFn(1, 'b')); // undefined

Mocking with custom matchers

This feature allows you to use Jest's built-in matchers to define mock behavior, making it easier to handle a wide range of input scenarios.

const { when } = require('jest-when');
const mockFn = jest.fn();

when(mockFn).calledWith(expect.any(Number)).mockReturnValue('number');
when(mockFn).calledWith(expect.any(String)).mockReturnValue('string');

console.log(mockFn(123)); // 'number'
console.log(mockFn('abc')); // 'string'
console.log(mockFn(true)); // undefined

Other packages similar to jest-when

sinon

Sinon is a popular standalone test spy, stub, and mock library for JavaScript. It provides similar functionality to jest-when but is more comprehensive, offering a wider range of features for test doubles. Unlike jest-when, Sinon is not specifically designed for Jest and can be used with other testing frameworks.

testdouble

Testdouble is a library for creating test doubles (mocks, stubs, and spies) in JavaScript. It offers a similar feature set to jest-when but is designed to be framework-agnostic, meaning it can be used with various testing frameworks, not just Jest. Testdouble focuses on providing a simple and intuitive API for creating and managing test doubles.

README

jest-when

npm i --save-dev jest-when

A sugary way to mock return values for specific arguments only.

Basic usage:

import when from 'jest-when';

const fn = jest.fn();
when(fn).calledWith(1).mockReturnValue('yay!');

const result = fn(1);
expect(result).toEqual('yay!');

Supports multiple args:

import when from 'jest-when';

const fn = jest.fn();
when(fn).calledWith(1, true, 'foo').mockReturnValue('yay!');

const result = fn(1, true, 'foo');
expect(result).toEqual('yay!');

Supports jest matchers:

import when from 'jest-when';

const fn = jest.fn();
when(fn).calledWith(
  expect.anything(),
  expect.any(Number),
  expect.arrayContaining(false)
).mockReturnValue('yay!');

const result = fn('whatever', 100, [true, false]);
expect(result).toEqual('yay!');

Supports compound declarations:

import when from 'jest-when';

const fn = jest.fn();
when(fn).calledWith(1).mockReturnValue('no');
when(fn).calledWith(2).mockReturnValue('way?');
when(fn).calledWith(3).mockReturnValue('yes');
when(fn).calledWith(4).mockReturnValue('way!');

expect(fn(1)).toEqual('no');
expect(fn(2)).toEqual('way?');
expect(fn(3)).toEqual('yes');
expect(fn(4)).toEqual('way!');
expect(fn(5)).toEqual(undefined);

Assert args for debugging:

Just pass true as second param to .mockReturnValue(value, true). After that your test will fail if the jest mock function is ever called without those exact calledWith params.

import when from 'jest-when';

const fn = jest.fn();
when(fn).calledWith(1).mockReturnValue('x');

fn(2); // Will throw a helpful jest assertion error with diff