jest-mock-extended

Install the package as a development dependency using npm or yarn.

npm install jest-mock-extended --save-dev

or

yarn add jest-mock-extended --dev

Use mockDeep() to create a mock object where all nested properties and methods are also automatically mocked. This returns a DeepMockProxy, which is useful for complex objects with deep hierarchies where you want to avoid manually mocking every sub-property.

import { mockDeep } from 'jest-mock-extended';

const deepMock = mockDeep<ComplexType>();
// deepMock.nestedProperty.method() is also a mock

The stub<T>() function creates a proxy of type T. Unlike mock(), it does not create complex Jest mocks for every property. Instead, if you access a property that does not exist on the object, it returns a jest.fn(). This is useful for lightweight stubs where you only care about a few specific method calls.

import { stub } from 'jest-mock-extended';

interface Simple {
  doSomething: () => void;
}

const s = stub<Simple>();
// s.doSomething is a jest.fn()
s.doSomething();

The mock function creates a MockProxy<T>. This proxy automatically mocks all properties of the type T. If a property is a function, it is automatically turned into a Jest mock function with the calledWith extension.

• mock(mockImplementation?: DeepPartial<T>, opts?: MockOpts)
• opts.deep: (Boolean) If true, enables deep mocking (see mockDeep).
• opts.fallbackMockImplementation: (Function) A function to provide a default implementation for mocked properties.

import { mock } from 'jest-mock-extended';

interface User {
  id: string;
  getName: () => string;
}

const userMock = mock<User>();

// userMock.getName is now a jest.fn()
userMock.getName.mockReturnValue('John Doe');

If the built-in matchers do not satisfy your requirements, you can create a custom matcher using the matches() function. This function accepts a predicate function (a MatcherFn<T>) that returns true if the value matches your criteria.

matches<T>((actualValue: T) => boolean)

import { matches } from 'jest-mock-extended';

// Create a matcher that checks if a string starts with a specific prefix
const startsWithHello = matches((val: string) => val.startsWith('Hello'));

expect(mock.method).toHaveBeenCalledWith(startsWithHello());

These utilities allow you to recursively clear or reset all mock state within a MockProxy or DeepMockProxy.

• mockClear(mock: MockProxy<any>): Clears the state of all mock functions (calls, instances, etc.) within the proxy and its nested mocks.
• mockReset(mock: MockProxy<any>): Resets all mock functions to their initial state (removes any mocked implementations) within the proxy and its nested mocks.

import { mock, mockClear, mockReset } from 'jest-mock-extended';

const service = mock<MyService>();

// ... perform tests ...

mockClear(service); // Clears call history
mockReset(service); // Clears history AND implementations

The captor() utility allows you to both validate an argument in an expectation and extract the actual value(s) passed to a mock for further assertions.

A CaptorMatcher acts as an asymmetric matcher that, when matched, stores the actualValue in its .value property and pushes all matched values into its .values array.

Use this when you need to perform complex assertions on the arguments that are difficult to express with standard matchers.

import { captor } from 'jest-mock-extended';

const myCaptor = captor<MyType>();

// Use the captor in the expectation
expect(mock.method).toHaveBeenCalledWith(myCaptor());

// Access the captured values for detailed assertions
const capturedValue = myCaptor.value;
const allCapturedValues = myCaptor.values;

expect(capturedValue.someProperty).toBe('specific-value');

Use JestMockExtended.configure to set global configuration for mocks. A common use case is using ignoreProps to prevent the mock from returning values for specific properties (e.g., when mocking a Promise, you might want to ignore then to avoid unexpected behavior).

• configure(config: GlobalConfig): Performs a shallow merge of your config with the DEFAULT_CONFIG.
• resetConfig(): Resets the global configuration to DEFAULT_CONFIG.
• DEFAULT_CONFIG: Contains { ignoreProps: ['then'] } by default.

import { JestMockExtended } from 'jest-mock-extended';

JestMockExtended.configure({
  ignoreProps: ['then', 'someOtherProp']
});

// To revert to defaults
JestMockExtended.resetConfig();

To maintain clean tests, you can manage the state of your mocks using these utility functions:

• mockClear(mock): Clears the state of the mock (e.g., call history, instances) but keeps the implementation/return values intact.
• mockReset(mock): Resets the mock to its initial state, clearing both the call history and any mocked implementations/return values.

import { mockClear, mockReset } from 'jest-mock-extended';

const myMock = mock<MyType>();

// After some interactions:
mockClear(myMock);
// or
mockReset(myMock);