Skip to content

A when(fn).calledWith(args).thenReturn(value) lib for jest

License

Notifications You must be signed in to change notification settings

idan-at/jest-when

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

21 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

jest-when

build status codecov GitHub license npm

An extended, sugary way to mock return values for specific arguments only

Many thanks to @jonasholtkamp. He forked this repo when I was inactive and stewarded several key features and bug fixes!

Features

jest-when allows you to use a set of the original Jest mock functions in order to train your mocks only based on parameters your mocked function is called with.

An example statement would be as follows:

when(fn).calledWith(1).mockReturnValue('yay!')

The trained mock function fn will now behave as follows -- assumed no other trainings took place:

  • return yay! if called with 1 as first parameter
  • return undefined if called with any other first parameter than 1

For extended usage see the examples below.

The supported set of mock functions is:

  • mockReturnValue
  • mockReturnValueOnce
  • mockResolvedValue
  • mockResolvedValueOnce
  • mockRejectedValue
  • mockRejectedValueOnce

Usage

Installation

npm i --save-dev jest-when

Basic usage:

import { when } from 'jest-when'

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

expect(fn(1)).toEqual('yay!')

Supports chaining of mock trainings:

when(fn)
  .calledWith(1).mockReturnValue('yay!')
  .calledWith(2).mockReturnValue('nay!')

expect(fn(1)).toEqual('yay!')
expect(fn(2)).toEqual('nay!')

Thanks to @fkloes.

when(fn)
  .calledWith(1)
  .mockReturnValueOnce('yay!')
  .mockReturnValue('nay!')

expect(fn(1)).toEqual('yay!')
expect(fn(1)).toEqual('nay!')

Thanks to @danielhusar.

Supports replacement of mock trainings:

when(fn).calledWith(1).mockReturnValue('yay!')
expect(fn(1)).toEqual('yay!')

when(fn).calledWith(1).mockReturnValue('nay!')
expect(fn(1)).toEqual('nay!')

This replacement of the training does only happen for mock functions not ending in *Once. Trainings like mockReturnValueOnce are removed after a matching function call anyway.

Thanks to @fkloes.

Supports multiple args with partial argument matching:

when(fn).calledWith(1, true).mockReturnValue('yay!')

expect(fn(1, true)).toEqual('yay!')
expect(fn(1, true, 'foo')).toEqual('yay!')

Supports training for single calls

when(fn).calledWith(1, true, 'foo').mockReturnValueOnce('yay!')
when(fn).calledWith(1, true, 'foo').mockReturnValueOnce('nay!')

expect(fn(1, true, 'foo')).toEqual('yay!')
expect(fn(1, true, 'foo')).toEqual('nay!')
expect(fn(1, true, 'foo')).toBeUndefined()

Supports Promises, both resolved and rejected

when(fn).calledWith(1).mockResolvedValue('yay!')
when(fn).calledWith(2).mockResolvedValueOnce('nay!')

await expect(fn(1)).resolves.toEqual('yay!')
await expect(fn(1)).resolves.toEqual('yay!')

await expect(fn(2)).resolves.toEqual('nay!')
expect(await fn(2)).toBeUndefined()


when(fn).calledWith(3).mockRejectedValue(new Error('oh no!'))
when(fn).calledWith(4).mockRejectedValueOnce(new Error('oh no, an error again!'))

await expect(fn(3)).rejects.toThrow('oh no!')
await expect(fn(3)).rejects.toThrow('oh no!')

await expect(fn(4)).rejects.toThrow('oh no, an error again!')
expect(await fn(4)).toBeUndefined()

Supports jest matchers:

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:

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 the args:

Use expectCalledWith instead to run an assertion that the fn was called with the provided args. Your test will fail if the jest mock function is ever called without those exact expectCalledWith params.

Disclaimer: This won't really work very well with compound declarations, because one of them will always fail, and throw an assertion error.

when(fn).expectCalledWith(1).mockReturnValue('x')

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

Supports default behavior

Use any of mockReturnValue, mockResolvedValue or mockRejectedValue directly on the object to set up a default behavior, which will serve as fallback if no matcher fits.

when(fn)
  .mockReturnValue('default')
  .calledWith('foo').mockReturnValue('special')

expect(fn('foo')).toEqual('special')
expect(fn('bar')).toEqual('default')

Contributors (in order of contribution)

About

A when(fn).calledWith(args).thenReturn(value) lib for jest

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%