Interface Matchers<R, T>

interface Matchers<R, T = {}> {
    toEqualBindings: (actual: Bindings) => R;
    toEqualBindingsArray: (actual: Bindings[]) => R;
    toEqualBindingsStream: (actual: Bindings[]) => Promise<R>;
    toFailTest: (actual: string) => R;
    toPassTest: (actual: any) => R;
    toPassTestVoid: () => R;
    lastCalledWith<E extends any[]>(...args: E): R;
    lastReturnedWith<E = any>(expected?: E): R;
    nthCalledWith<E extends any[]>(nthCall: number, ...params: E): R;
    nthReturnedWith<E = any>(n: number, expected?: E): R;
    toBe<E = any>(expected: E): R;
    toBeCalled(): R;
    toBeCalledTimes(expected: number): R;
    toBeCalledWith<E extends any[]>(...args: E): R;
    toBeCloseTo(expected: number, numDigits?: number): R;
    toBeDefined(): R;
    toBeFalsy(): R;
    toBeGreaterThan(expected: number | bigint): R;
    toBeGreaterThanOrEqual(expected: number | bigint): R;
    toBeInstanceOf<E = any>(expected: E): R;
    toBeLessThan(expected: number | bigint): R;
    toBeLessThanOrEqual(expected: number | bigint): R;
    toBeNaN(): R;
    toBeNull(): R;
    toBeTruthy(): R;
    toBeUndefined(): R;
    toContain<E = any>(expected: E): R;
    toContainEqual<E = any>(expected: E): R;
    toEqual<E = any>(expected: E): R;
    toHaveBeenCalled(): R;
    toHaveBeenCalledTimes(expected: number): R;
    toHaveBeenCalledWith<E extends any[]>(...params: E): R;
    toHaveBeenLastCalledWith<E extends any[]>(...params: E): R;
    toHaveBeenNthCalledWith<E extends any[]>(nthCall: number, ...params: E): R;
    toHaveLastReturnedWith<E = any>(expected?: E): R;
    toHaveLength(expected: number): R;
    toHaveNthReturnedWith<E = any>(nthCall: number, expected?: E): R;
    toHaveProperty<E = any>(
        propertyPath: string | readonly any[],
        value?: E,
    ): R;
    toHaveReturned(): R;
    toHaveReturnedTimes(expected: number): R;
    toHaveReturnedWith<E = any>(expected?: E): R;
    toMatch(expected: string | RegExp): R;
    toMatchInlineSnapshot<U extends { [P in string | number | symbol]: any }>(
        propertyMatchers: Partial<U>,
        snapshot?: string,
    ): R;
    toMatchInlineSnapshot(snapshot?: string): R;
    toMatchObject<E extends {} | any[]>(expected: E): R;
    toMatchSnapshot<U extends { [P in string | number | symbol]: any }>(
        propertyMatchers: Partial<U>,
        snapshotName?: string,
    ): R;
    toMatchSnapshot(snapshotName?: string): R;
    toReturn(): R;
    toReturnTimes(count: number): R;
    toReturnWith<E = any>(value?: E): R;
    toStrictEqual<E = any>(expected: E): R;
    toThrow(error?: string | RegExp | Constructable | Error): R;
    toThrowError(error?: string | RegExp | Constructable | Error): R;
    toThrowErrorMatchingInlineSnapshot(snapshot?: string): R;
    toThrowErrorMatchingSnapshot(snapshotName?: string): R;
}

Type Parameters

  • R
  • T = {}

Properties

toEqualBindings toEqualBindingsArray toEqualBindingsStream toFailTest toPassTest toPassTestVoid

Methods

lastCalledWith lastReturnedWith nthCalledWith nthReturnedWith toBe toBeCalled toBeCalledTimes toBeCalledWith toBeCloseTo toBeDefined toBeFalsy toBeGreaterThan toBeGreaterThanOrEqual toBeInstanceOf toBeLessThan toBeLessThanOrEqual toBeNaN toBeNull toBeTruthy toBeUndefined toContain toContainEqual toEqual toHaveBeenCalled toHaveBeenCalledTimes toHaveBeenCalledWith toHaveBeenLastCalledWith toHaveBeenNthCalledWith toHaveLastReturnedWith toHaveLength toHaveNthReturnedWith toHaveProperty toHaveReturned toHaveReturnedTimes toHaveReturnedWith toMatch toMatchInlineSnapshot toMatchObject toMatchSnapshot toReturn toReturnTimes toReturnWith toStrictEqual toThrow toThrowError toThrowErrorMatchingInlineSnapshot toThrowErrorMatchingSnapshot

Properties

toEqualBindings

toEqualBindings: (actual: Bindings) => R

toEqualBindingsArray

toEqualBindingsArray: (actual: Bindings[]) => R

toEqualBindingsStream

toEqualBindingsStream: (actual: Bindings[]) => Promise<R>

toFailTest

toFailTest: (actual: string) => R

toPassTest

toPassTest: (actual: any) => R

toPassTestVoid

toPassTestVoid: () => R

Methods

lastCalledWith

  • lastCalledWith<E extends any[]>(...args: E): R

  • Ensures the last call to a mock function was provided specific args.

    Optionally, you can provide a type for the expected arguments via a generic. Note that the type must be either an array or a tuple.

    Type Parameters

    • E extends any[]

    Parameters

    • ...args: E

    Returns R

    Deprecated

    in favor of toHaveBeenLastCalledWith

lastReturnedWith

  • lastReturnedWith<E = any>(expected?: E): R

  • Ensure that the last call to a mock function has returned a specified value.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • Optionalexpected: E

    Returns R

    Deprecated

    in favor of toHaveLastReturnedWith

nthCalledWith

  • nthCalledWith<E extends any[]>(nthCall: number, ...params: E): R

  • Ensure that a mock function is called with specific arguments on an Nth call.

    Optionally, you can provide a type for the expected arguments via a generic. Note that the type must be either an array or a tuple.

    Type Parameters

    • E extends any[]

    Parameters

    • nthCall: number
    • ...params: E

    Returns R

    Deprecated

    in favor of toHaveBeenNthCalledWith

nthReturnedWith

  • nthReturnedWith<E = any>(n: number, expected?: E): R

  • Ensure that the nth call to a mock function has returned a specified value.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • n: number
    • Optionalexpected: E

    Returns R

    Deprecated

    in favor of toHaveNthReturnedWith

toBe

  • toBe<E = any>(expected: E): R

  • Checks that a value is what you expect. It uses Object.is to check strict equality. Don't use toBe with floating-point numbers.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • expected: E

    Returns R

toBeCalled

  • toBeCalled(): R

  • Ensures that a mock function is called.

    Returns R

    Deprecated

    in favor of toHaveBeenCalled

toBeCalledTimes

  • toBeCalledTimes(expected: number): R

  • Ensures that a mock function is called an exact number of times.

    Parameters

    • expected: number

    Returns R

    Deprecated

    in favor of toHaveBeenCalledTimes

toBeCalledWith

  • toBeCalledWith<E extends any[]>(...args: E): R

  • Ensure that a mock function is called with specific arguments.

    Optionally, you can provide a type for the expected arguments via a generic. Note that the type must be either an array or a tuple.

    Type Parameters

    • E extends any[]

    Parameters

    • ...args: E

    Returns R

    Deprecated

    in favor of toHaveBeenCalledWith

toBeCloseTo

  • toBeCloseTo(expected: number, numDigits?: number): R

  • Using exact equality with floating point numbers is a bad idea. Rounding means that intuitive things fail. The default for numDigits is 2.

    Parameters

    • expected: number
    • OptionalnumDigits: number

    Returns R

toBeDefined

  • toBeDefined(): R

  • Ensure that a variable is not undefined.

    Returns R

toBeFalsy

  • toBeFalsy(): R

  • When you don't care what a value is, you just want to ensure a value is false in a boolean context.

    Returns R

toBeGreaterThan

  • toBeGreaterThan(expected: number | bigint): R

  • For comparing floating point or big integer numbers.

    Parameters

    • expected: number | bigint

    Returns R

toBeGreaterThanOrEqual

  • toBeGreaterThanOrEqual(expected: number | bigint): R

  • For comparing floating point or big integer numbers.

    Parameters

    • expected: number | bigint

    Returns R

toBeInstanceOf

  • toBeInstanceOf<E = any>(expected: E): R

  • Ensure that an object is an instance of a class. This matcher uses instanceof underneath.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • expected: E

    Returns R

toBeLessThan

  • toBeLessThan(expected: number | bigint): R

  • For comparing floating point or big integer numbers.

    Parameters

    • expected: number | bigint

    Returns R

toBeLessThanOrEqual

  • toBeLessThanOrEqual(expected: number | bigint): R

  • For comparing floating point or big integer numbers.

    Parameters

    • expected: number | bigint

    Returns R

toBeNaN

  • toBeNaN(): R

  • Used to check that a variable is NaN.

    Returns R

toBeNull

  • toBeNull(): R

  • This is the same as .toBe(null) but the error messages are a bit nicer. So use .toBeNull() when you want to check that something is null.

    Returns R

toBeTruthy

  • toBeTruthy(): R

  • Use when you don't care what a value is, you just want to ensure a value is true in a boolean context. In JavaScript, there are six falsy values: false, 0, '', null, undefined, and NaN. Everything else is truthy.

    Returns R

toBeUndefined

  • toBeUndefined(): R

  • Used to check that a variable is undefined.

    Returns R

toContain

  • toContain<E = any>(expected: E): R

  • Used when you want to check that an item is in a list. For testing the items in the list, this uses ===, a strict equality check. It can also check whether a string is a substring of another string.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • expected: E

    Returns R

toContainEqual

  • toContainEqual<E = any>(expected: E): R

  • Used when you want to check that an item is in a list. For testing the items in the list, this matcher recursively checks the equality of all fields, rather than checking for object identity.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • expected: E

    Returns R

toEqual

  • toEqual<E = any>(expected: E): R

  • Used when you want to check that two objects have the same value. This matcher recursively checks the equality of all fields, rather than checking for object identity.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • expected: E

    Returns R

toHaveBeenCalled

  • toHaveBeenCalled(): R

  • Ensures that a mock function is called.

    Returns R

toHaveBeenCalledTimes

  • toHaveBeenCalledTimes(expected: number): R

  • Ensures that a mock function is called an exact number of times.

    Parameters

    • expected: number

    Returns R

toHaveBeenCalledWith

  • toHaveBeenCalledWith<E extends any[]>(...params: E): R

  • Ensure that a mock function is called with specific arguments.

    Optionally, you can provide a type for the expected arguments via a generic. Note that the type must be either an array or a tuple.

    Type Parameters

    • E extends any[]

    Parameters

    • ...params: E

    Returns R

toHaveBeenLastCalledWith

  • toHaveBeenLastCalledWith<E extends any[]>(...params: E): R

  • If you have a mock function, you can use .toHaveBeenLastCalledWith to test what arguments it was last called with.

    Optionally, you can provide a type for the expected arguments via a generic. Note that the type must be either an array or a tuple.

    Type Parameters

    • E extends any[]

    Parameters

    • ...params: E

    Returns R

toHaveBeenNthCalledWith

  • toHaveBeenNthCalledWith<E extends any[]>(nthCall: number, ...params: E): R

  • Ensure that a mock function is called with specific arguments on an Nth call.

    Optionally, you can provide a type for the expected arguments via a generic. Note that the type must be either an array or a tuple.

    Type Parameters

    • E extends any[]

    Parameters

    • nthCall: number
    • ...params: E

    Returns R

toHaveLastReturnedWith

  • toHaveLastReturnedWith<E = any>(expected?: E): R

  • Use to test the specific value that a mock function last returned. If the last call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • Optionalexpected: E

    Returns R

toHaveLength

  • toHaveLength(expected: number): R

  • Used to check that an object has a .length property and it is set to a certain numeric value.

    Parameters

    • expected: number

    Returns R

toHaveNthReturnedWith

  • toHaveNthReturnedWith<E = any>(nthCall: number, expected?: E): R

  • Use to test the specific value that a mock function returned for the nth call. If the nth call to the mock function threw an error, then this matcher will fail no matter what value you provided as the expected return value.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • nthCall: number
    • Optionalexpected: E

    Returns R

toHaveProperty

  • toHaveProperty<E = any>(propertyPath: string | readonly any[], value?: E): R

  • Use to check if property at provided reference keyPath exists for an object. For checking deeply nested properties in an object you may use dot notation or an array containing the keyPath for deep references.

    Optionally, you can provide a value to check if it's equal to the value present at keyPath on the target object. This matcher uses 'deep equality' (like toEqual()) and recursively checks the equality of all fields.

    Type Parameters

    • E = any

    Parameters

    • propertyPath: string | readonly any[]
    • Optionalvalue: E

    Returns R

    Example

    expect(houseForSale).toHaveProperty('kitchen.area', 20);

toHaveReturned

  • toHaveReturned(): R

  • Use to test that the mock function successfully returned (i.e., did not throw an error) at least one time

    Returns R

toHaveReturnedTimes

  • toHaveReturnedTimes(expected: number): R

  • Use to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned.

    Parameters

    • expected: number

    Returns R

toHaveReturnedWith

  • toHaveReturnedWith<E = any>(expected?: E): R

  • Use to ensure that a mock function returned a specific value.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • Optionalexpected: E

    Returns R

toMatch

  • toMatch(expected: string | RegExp): R

  • Check that a string matches a regular expression.

    Parameters

    • expected: string | RegExp

    Returns R

toMatchInlineSnapshot

  • toMatchInlineSnapshot<U extends { [P in string | number | symbol]: any }>(
        propertyMatchers: Partial<U>,
        snapshot?: string,
    ): R

  • This ensures that a value matches the most recent snapshot with property matchers. Instead of writing the snapshot value to a .snap file, it will be written into the source code automatically. Check out the Snapshot Testing guide for more information.

    Type Parameters

    • U extends { [P in string | number | symbol]: any }

    Parameters

    • propertyMatchers: Partial<U>
    • Optionalsnapshot: string

    Returns R

  • toMatchInlineSnapshot(snapshot?: string): R

  • This ensures that a value matches the most recent snapshot with property matchers. Instead of writing the snapshot value to a .snap file, it will be written into the source code automatically. Check out the Snapshot Testing guide for more information.

    Parameters

    • Optionalsnapshot: string

    Returns R

toMatchObject

  • toMatchObject<E extends {} | any[]>(expected: E): R

  • Used to check that a JavaScript object matches a subset of the properties of an object

    Optionally, you can provide an object to use as Generic type for the expected value. This ensures that the matching object matches the structure of the provided object-like type.

    Type Parameters

    • E extends {} | any[]

    Parameters

    • expected: E

    Returns R

    Example

    type House = {
      bath: boolean;
      bedrooms: number;
      kitchen: {
        amenities: string[];
        area: number;
        wallColor: string;
      }
    };

    expect(desiredHouse).toMatchObject<House>({...standardHouse, kitchen: {area: 20}}) // wherein standardHouse is some base object of type House

toMatchSnapshot

  • toMatchSnapshot<U extends { [P in string | number | symbol]: any }>(
        propertyMatchers: Partial<U>,
        snapshotName?: string,
    ): R

  • This ensures that a value matches the most recent snapshot with property matchers. Check out the Snapshot Testing guide for more information.

    Type Parameters

    • U extends { [P in string | number | symbol]: any }

    Parameters

    • propertyMatchers: Partial<U>
    • OptionalsnapshotName: string

    Returns R

  • toMatchSnapshot(snapshotName?: string): R

  • This ensures that a value matches the most recent snapshot. Check out the Snapshot Testing guide for more information.

    Parameters

    • OptionalsnapshotName: string

    Returns R

toReturn

  • toReturn(): R

  • Ensure that a mock function has returned (as opposed to thrown) at least once.

    Returns R

    Deprecated

    in favor of toHaveReturned

toReturnTimes

  • toReturnTimes(count: number): R

  • Ensure that a mock function has returned (as opposed to thrown) a specified number of times.

    Parameters

    • count: number

    Returns R

    Deprecated

    in favor of toHaveReturnedTimes

toReturnWith

  • toReturnWith<E = any>(value?: E): R

  • Ensure that a mock function has returned a specified value at least once.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • Optionalvalue: E

    Returns R

    Deprecated

    in favor of toHaveReturnedWith

toStrictEqual

  • toStrictEqual<E = any>(expected: E): R

  • Use to test that objects have the same types as well as structure.

    Optionally, you can provide a type for the expected value via a generic. This is particularly useful for ensuring expected objects have the right structure.

    Type Parameters

    • E = any

    Parameters

    • expected: E

    Returns R

toThrow

  • toThrow(error?: string | RegExp | Constructable | Error): R

  • Used to test that a function throws when it is called.

    Parameters

    Returns R

toThrowError

  • toThrowError(error?: string | RegExp | Constructable | Error): R

  • If you want to test that a specific error is thrown inside a function.

    Parameters

    Returns R

    Deprecated

    in favor of toThrow

toThrowErrorMatchingInlineSnapshot

  • toThrowErrorMatchingInlineSnapshot(snapshot?: string): R

  • Used to test that a function throws a error matching the most recent snapshot when it is called. Instead of writing the snapshot value to a .snap file, it will be written into the source code automatically.

    Parameters

    • Optionalsnapshot: string

    Returns R

toThrowErrorMatchingSnapshot

  • toThrowErrorMatchingSnapshot(snapshotName?: string): R

  • Used to test that a function throws a error matching the most recent snapshot when it is called.

    Parameters

    • OptionalsnapshotName: string

    Returns R

Settings

Member Visibility

On This Page

Properties
Methods