xJet.mock – Mock Any Global Function, Method, Constructor, or Value

The xJet.mock() utility enables you to replace existing global or object-bound functions, class methods, constructors, or even primitive values with powerful, controllable mocks. This allows you to intercept invocations, inspect arguments/results, return custom values, and later restore the original behavior seamlessly.

What Does xJet.mock Do?

• Swaps out an existing function, constructor, or value with a controllable mock.
• Tracks calls, arguments, results, and instances (for functions and constructors).
• Customizes behavior: supply new logic (mock implementation), return values, or errors.
• Restores the original implementation or value at any time.

Mocking a Regular Function

function sayHello(name) {
    return `Hello, ${ name }!`;
}

test('some test', () => {
    const sayHelloMock = xJet.mock(sayHello);
    sayHelloMock.mockImplementation(() => 'Hi!');

    expect(sayHello('Bob')).toBe('Hi!');

    sayHelloMock.mockRestore();
    expect(sayHello('Bob')).toBe('Hello, Bob!');
});

Mocking a Constructor

class User {
    name: string;

    constructor(name: string) {
        this.name = name;
    }
}

test('some test', () => {
    const userMock = xJet.mock(User);
    userMock.mockImplementation((name) => ({ name: name + ' (mocked)' }));

    const instance = new User('Alice');
    expect(instance.name).toBe('Alice (mocked)');

    userMock.mockRestore();
    const real = new User('Alice');
    expect(real.name).toBe('Alice');
});

Mocking Primitive Values and Properties

You can also mock primitive values on objects:

// config.ts

export const config = { apiUrl: 'https://api.example.com', timeout: 5000 };

import { config } from './config';

test('config override', () => {
    const mockConfig = xJet.mock(config, () => ({
        apiUrl: 'https://test-api.example.com',
        timeout: 10000
    }));

    expect(config.apiUrl).toBe('https://test-api.example.com');

    apiUrlMock.mockRestore();
    expect(config.apiUrl).toBe('https://api.example.com');
});

WARNING

Important: xJet.mock() does not work with object properties like config.apiUrl. For mocking object properties or methods, use xJet.spyOn() instead.

Mocking Global/Static Methods

You can use xJet.mock() to mock any function on the globalThis scope or within objects.

API Overview

The returned mock exposes all MockState methods and properties, providing extensive control and insight:

Method / Property	Description
mockReturnValue(value)	Always returns value when called.
mockReturnValueOnce(value)	Returns value for the next call, then goes back to the default/mock implementation.
mockImplementation(fn)	Sets or replaces the implementation function/logic.
mockImplementationOnce(fn)	Sets an implementation only valid for the next call.
mockResolvedValue(value)	Returns a resolved Promise with value (async).
mockRejectedValue(error)	Returns a rejected Promise with value/error (async).
mockRestore()	Restores the original function/constructor.
mockReset()	Completely resets mock state and history.
mockClear()	Clears all collected call data only, keeping the implementation.
getMockImplementation()	Gets the current implementation.
original(...args)	Directly call the original unmocked function/constructor.
mock.calls	Array of all calls ([[args1], [args2], ...]).
mock.results	Array of call results: { type: "return", value: "throw" }.
mock.instances	Constructed instances if used as a constructor.
mock.contexts	Value of this for each call.
getMockName()	Returns name of the mock (for compatibility/testing utilities).

Features

• Non-invasive: You can always recover the original implementation.
• Flexible: Works with both plain functions and constructors.
• Fine control: Use .mockImplementationOnce() or .mockReturnValueOnce() for per-call overrides.
• Tracking: Access full call/instance history for assertions in your tests.

Best Practices

• Always call .mockRestore() at the end of your test to clean up!
• If mocking fails (e.g., non-global or already replaced), check that the target is referenced correctly.

See Also

• xJet.fn
• xJet.spy