Mock Functions
Mock functions are also known as "spies", because they let you spy on the behavior of a function that is called indirectly by some other code, rather than only testing the output. You can create a mock function with jest.fn()
. If no implementation is given, the mock function will return undefined
when invoked.
#
Methods- Reference
mockFn.getMockName()
mockFn.mock.calls
mockFn.mock.results
mockFn.mock.instances
mockFn.mockClear()
mockFn.mockReset()
mockFn.mockRestore()
mockFn.mockImplementation(fn)
mockFn.mockImplementationOnce(fn)
mockFn.mockName(value)
mockFn.mockReturnThis()
mockFn.mockReturnValue(value)
mockFn.mockReturnValueOnce(value)
mockFn.mockResolvedValue(value)
mockFn.mockResolvedValueOnce(value)
mockFn.mockRejectedValue(value)
mockFn.mockRejectedValueOnce(value)
- TypeScript
#
ReferencemockFn.getMockName()
#
Returns the mock name string set by calling mockFn.mockName(value)
.
mockFn.mock.calls
#
An array containing the call arguments of all calls that have been made to this mock function. Each item in the array is an array of arguments that were passed during the call.
For example: A mock function f
that has been called twice, with the arguments f('arg1', 'arg2')
, and then with the arguments f('arg3', 'arg4')
, would have a mock.calls
array that looks like this:
mockFn.mock.results
#
An array containing the results of all calls that have been made to this mock function. Each entry in this array is an object containing a type
property, and a value
property. type
will be one of the following:
'return'
- Indicates that the call completed by returning normally.'throw'
- Indicates that the call completed by throwing a value.'incomplete'
- Indicates that the call has not yet completed. This occurs if you test the result from within the mock function itself, or from within a function that was called by the mock.
The value
property contains the value that was thrown or returned. value
is undefined when type === 'incomplete'
.
For example: A mock function f
that has been called three times, returning 'result1'
, throwing an error, and then returning 'result2'
, would have a mock.results
array that looks like this:
mockFn.mock.instances
#
An array that contains all the object instances that have been instantiated from this mock function using new
.
For example: A mock function that has been instantiated twice would have the following mock.instances
array:
mockFn.mockClear()
#
Resets all information stored in the mockFn.mock.calls
and mockFn.mock.instances
arrays.
Often this is useful when you want to clean up a mock's usage data between two assertions.
Beware that mockClear
will replace mockFn.mock
, not just mockFn.mock.calls
and mockFn.mock.instances
. You should, therefore, avoid assigning mockFn.mock
to other variables, temporary or not, to make sure you don't access stale data.
The clearMocks
configuration option is available to clear mocks automatically between tests.
mockFn.mockReset()
#
Does everything that mockFn.mockClear()
does, and also removes any mocked return values or implementations.
This is useful when you want to completely reset a mock back to its initial state. (Note that resetting a spy will result in a function with no return value).
Beware that mockReset
will replace mockFn.mock
, not just mockFn.mock.calls
and mockFn.mock.instances
. You should, therefore, avoid assigning mockFn.mock
to other variables, temporary or not, to make sure you don't access stale data.
mockFn.mockRestore()
#
Does everything that mockFn.mockReset()
does, and also restores the original (non-mocked) implementation.
This is useful when you want to mock functions in certain test cases and restore the original implementation in others.
Beware that mockFn.mockRestore
only works when the mock was created with jest.spyOn
. Thus you have to take care of restoration yourself when manually assigning jest.fn()
.
The restoreMocks
configuration option is available to restore mocks automatically between tests.
mockFn.mockImplementation(fn)
#
Accepts a function that should be used as the implementation of the mock. The mock itself will still record all calls that go into and instances that come from itself – the only difference is that the implementation will also be executed when the mock is called.
Note: jest.fn(implementation)
is a shorthand for jest.fn().mockImplementation(implementation)
.
For example:
mockImplementation
can also be used to mock class constructors:
mockFn.mockImplementationOnce(fn)
#
Accepts a function that will be used as an implementation of the mock for one call to the mocked function. Can be chained so that multiple function calls produce different results.
When the mocked function runs out of implementations defined with mockImplementationOnce, it will execute the default implementation set with jest.fn(() => defaultValue)
or .mockImplementation(() => defaultValue)
if they were called:
mockFn.mockName(value)
#
Accepts a string to use in test result output in place of "jest.fn()" to indicate which mock function is being referenced.
For example:
Will result in this error:
mockFn.mockReturnThis()
#
Syntactic sugar function for:
mockFn.mockReturnValue(value)
#
Accepts a value that will be returned whenever the mock function is called.
mockFn.mockReturnValueOnce(value)
#
Accepts a value that will be returned for one call to the mock function. Can be chained so that successive calls to the mock function return different values. When there are no more mockReturnValueOnce
values to use, calls will return a value specified by mockReturnValue
.
mockFn.mockResolvedValue(value)
#
Syntactic sugar function for:
Useful to mock async functions in async tests:
mockFn.mockResolvedValueOnce(value)
#
Syntactic sugar function for:
Useful to resolve different values over multiple async calls:
mockFn.mockRejectedValue(value)
#
Syntactic sugar function for:
Useful to create async mock functions that will always reject:
mockFn.mockRejectedValueOnce(value)
#
Syntactic sugar function for:
Example usage:
#
TypeScriptJest itself is written in TypeScript.
If you are using Create React App then the TypeScript template has everything you need to start writing tests in TypeScript.
Otherwise, please see our Getting Started guide for to get setup with TypeScript.
You can see an example of using Jest with TypeScript in our GitHub repository.
jest.MockedFunction
#
jest.MockedFunction
is available in the@types/jest
module from version24.9.0
.
The following examples will assume you have an understanding of how Jest mock functions work with JavaScript.
You can use jest.MockedFunction
to represent a function that has been replaced by a Jest mock.
Example using automatic jest.mock
:
Example using jest.fn
:
jest.MockedClass
#
jest.MockedClass
is available in the@types/jest
module from version24.9.0
.
The following examples will assume you have an understanding of how Jest mock classes work with JavaScript.
You can use jest.MockedClass
to represent a class that has been replaced by a Jest mock.
Converting the ES6 Class automatic mock example would look like this: