hanbi/lib/main.d.ts

A small javascript library for stubbing and spying on methods/functions.

type FunctionLike = (...args: any[]) => any;
export interface StubCall<TArgs, TReturn> {
    readonly args: TArgs;
    readonly returnValue?: TReturn;
    readonly thisValue: unknown;
}
/**
 * Represents a single stubbed function
 */
export declare class Stub<T extends FunctionLike> {
    /**
     * Wrapped function
     */
    handler: T;
    /**
     * Function to be called when stub is restored
     */
    restoreCallback?: () => void;
    /**
     * Original function
     */
    original: T;
    protected _calls: Set<StubCall<Parameters<T>, ReturnType<T>>>;
    protected _returnValue?: ReturnType<T>;
    protected _returnFunction?: T;
    /**
     * Whether or not this stub has been called
     */
    get called(): boolean;
    /**
     * List of all calls this stub has received
     */
    get calls(): ReadonlySet<StubCall<Parameters<T>, ReturnType<T>>>;
    /**
     * Retrieves an individual call
     * @param index Index of the call to retrieve
     * @return Call at the specified index
     */
    getCall(index: number): StubCall<Parameters<T>, ReturnType<T>>;
    /**
     * Retrieves the first call
     * @return Call object
     */
    get firstCall(): StubCall<Parameters<T>, ReturnType<T>> | undefined;
    /**
     * Retrieves the last call
     * @return Call object
     */
    get lastCall(): StubCall<Parameters<T>, ReturnType<T>> | undefined;
    /**
     * Number of times this stub has been called
     */
    get callCount(): number;
    /**
     * Constructor
     * @param fn Function being stubbed
     */
    constructor(fn: T);
    /**
     * Processes an individual call to this stub
     * @param thisValue Context of the call (`this`)
     * @param args Arguments passed when being called
     * @return Return value of this call
     */
    protected _handleCall(thisValue: unknown, args: Parameters<T>): ReturnType<T> | undefined;
    /**
     * Specifies the value this stub should return
     * @param val Value to return
     */
    returns(val: ReturnType<T>): void;
    /**
     * Specifies a function to call to retrieve the return value of this
     * stub
     * @param fn Function to call
     */
    callsFake(fn: (...args: Parameters<T>) => ReturnType<T>): void;
    /**
     * Enables pass-through, in that the original function is called when
     * this stub is called.
     */
    passThrough(): void;
    /**
     * Resets call state (e.g. call count, calls, etc.)
     */
    reset(): void;
    /**
     * Restores this stub.
     * This behaviour differs depending on what created the stub.
     */
    restore(): void;
    /**
     * Asserts that the stub was called with a set of arguments
     * @param args Arguments to assert for
     * @return Whether they were passed or not
     */
    calledWith(...args: Parameters<T>): boolean;
    /**
     * Asserts that the stub returned a given value
     * @param val Value to check for
     * @return Whether the value was ever returned or not
     */
    returned(val: ReturnType<T>): boolean;
}
type StubbedFunction<T> = T extends FunctionLike ? T : FunctionLike;
/**
 * Stubs a method of a given object.
 * @param obj Object the method belongs to
 * @param method Method name to stub
 * @return Stubbed method
 */
export declare function stubMethod<TObj, TKey extends keyof TObj>(obj: TObj, method: TKey): Stub<StubbedFunction<TObj[TKey]>>;
/**
 * Stubs a given function.
 * @param fn Function to stub
 * @return Stubbed function
 */
export declare function stub<T extends FunctionLike>(fn: T): Stub<T>;
/**
 * Creates an anonymous spy.
 * @return Anonymous stub
 */
export declare function spy<T extends FunctionLike = FunctionLike>(): Stub<T>;
/**
 * Restores all tracked stubs at once.
 */
export declare function restore(): void;
export {};