vitest-mock-extended

When working with modules mocked via vi.mock, you may not be able to refer to the original object directly due to hoisting. Use these helpers to get type-safe access to mocked values:

• mocked(obj): Returns the mocked version of an object.
• mocked(obj, true): Returns a deep mocked version of an object.
• mockedFn(fn): Returns the mocked version of a function.
• isMockObject(val): A type guard to check if a value was created by mock() or mockDeep(). It narrows the type to MockProxy<T>.

import { mocked, mockedFn, isMockObject, type MockProxy } from "vitest-mock-extended";
import { originalObj, originalFn } from "somewhere";

const mockedObj = mocked(originalObj);
const deepMockedObj = mocked(originalObj, true);
const mockedFunction = mockedFn(originalFn);

// Type guard usage
const service: Service | MockProxy<Service> = getService();
if (isMockObject(service)) {
    service.request.mockReturnValue("mocked response");
}

If you need to mock an object where nested properties or returned objects also need to be mocks, use mockDeep<T>().

Configuration Options

• funcPropSupport: true: Enables support for properties that are themselves functions on the mocked object.
• fallbackMockImplementation: A function that is called if a return value hasn't been explicitly defined via calledWith.

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

// Basic deep mock
const mockObj: DeepMockProxy<Test1> = mockDeep<Test1>();
mockObj.deepProp.getNumber.calledWith(1).mockReturnValue(4);

// Deep mock with function property support
const mockObjWithFunc = mockDeep<Test1>({ funcPropSupport: true });
mockObjWithFunc.deepProp.calledWith(1).mockReturnValue(3);

// Deep mock with fallback implementation
const mockObjWithFallback = mockDeep<Test1>({
    fallbackMockImplementation: () => {
        throw new Error('please add expected return value using calledWith');
    },
});

The calledWith() extension allows you to define different behaviors or expectations based on the arguments passed to a mock function. It supports both exact values and matchers, and is fully type-checked.

Decorating existing Vitest mocks

To add calledWith to a function already mocked by Vitest's vi.mock, wrap it with mockFn():

import { vi } from 'vitest';
import { mockFn } from 'vitest-mock-extended';
import { aFunction } from './someThingIWantToMock';

vi.mock('./someThingIWantToMock');

const mockedAFunction = mockFn(aFunction);
// Now you can use calledWith
mockedAFunction.calledWith('foobar').mockReturnValue(true);

const provider = mock<PartyProvider>();
provider.getSongs.calledWith('disco party').mockReturnValue(['Dance the night away', 'Stayin Alive']);
expect(provider.getSongs('disco party')).toEqual(['Dance the night away', 'Stayin Alive']);

// Using Matchers
provider.getSongs.calledWith(any()).mockReturnValue(['Saw her standing there']);
provider.getSongs.calledWith(anyString()).mockReturnValue(['Saw her standing there']);

// Using mockFn for standalone functions
type MyFn = (x: number, y: number) => Promise<string>;
const fn = mockFn<MyFn>();
fn.calledWith(1, 2).mockReturnValue('str');

The following matchers are available for use within calledWith() to provide flexible argument expectations.

| Matcher | Description |
| ---------------------- | ---------------------------------------------------------- |
| any() | Matches any arg of any type. |
| anyBoolean() | Matches any boolean (true or false) |
| anyString() | Matches any string including empty string |
| anyNumber() | Matches any number that is not NaN |
| anyFunction() | Matches any function |
| anyObject() | Matches any object (typeof m === 'object') and is not null |
| anyArray() | Matches any array |
| anyMap() | Matches any Map |
| anySet() | Matches any Set |
| isA(class) | e.g isA(DiscoPartyProvider) |
| includes('value') | Checks if value is in the argument array |
| containsKey('key') | Checks if the key exists in the object |
| containsValue('value') | Checks if the value exists in an object |
| has('value') | checks if the value exists in a Set |
| notNull() | value !== null |
| notUndefined() | value !== undefined |
| notEmpty() | value !== undefined && value !== null && value !== '' |
| captor() | Used to capture an arg - alternative to mock.calls[0][0] |

The vitest-mock-extended library provides a set of asymmetric matchers that can be used within Vitest's expect() calls (e.g., in toHaveBeenCalledWith). These matchers allow you to verify that a mock was called with specific types or properties rather than exact values.

Commonly used matchers include:

• any(): Matches anything.
• anyString(), anyNumber(), anyBoolean(), anyFunction(), anySymbol(), anyObject(): Matches values of the specified type.
• anyArray(), anyMap(), anySet(): Matches specific collection types.
• isA(Class): Matches if the value is an instance of the provided class.
• notNull(), notUndefined(), notEmpty(): Matches values that are not null, not undefined, or not an empty string.
• arrayIncludes(value), setHas(value), mapHas(value): Matches collections that contain a specific value.
• objectContainsKey(key), objectContainsValue(value): Matches objects that contain a specific key or value.

import { anyString, isA, anyArray } from 'vitest-mock-extended';
import { expect, vi }

const myMock = vi.fn();

// Example usage in expectations
myMock('hello');
expect(myMock).toHaveBeenCalledWith(anyString());
expect(myMock).toHaveBeenCalledWith(isA(MyClass));
expect(myMock).toHaveBeenCalledWith(anyArray());