interface

test.AsymmetricMatchers

interface AsymmetricMatchers

Extend this interface with declaration merging to add type support for custom asymmetric matchers.

// my_modules.d.ts
interface MyCustomMatchers {
  toBeWithinRange(floor: number, ceiling: number): any;
}
declare module "bun:test" {
  interface Matchers<T> extends MyCustomMatchers {}
  interface AsymmetricMatchers extends MyCustomMatchers {}
}
  • constructor: (...args: any[]) => any | new (...args: any[]) => any
    ): any;

    Matches anything that was created with the given constructor. Use it inside toEqual or toBeCalledWith instead of a literal value.

    function randocall(fn) {
  return fn(Math.floor(Math.random() * 6 + 1));
}

test('randocall calls its callback with a number', () => {
  const mock = jest.fn();
  randocall(mock);
  expect(mock).toBeCalledWith(expect.any(Number));
});
  • anything(): any;

    Matches anything but null or undefined. Use it inside toEqual or toBeCalledWith instead of a literal value. For example, to check that a mock function is called with a non-null argument:

    test('map calls its argument with a non-null argument', () => {
  const mock = jest.fn();
  [1].map(x => mock(x));
  expect(mock).toBeCalledWith(expect.anything());
});
  • arrayContaining<E = any>(
    arr: readonly E[]
    ): any;

    Matches any array made up entirely of elements in the provided array. Use it inside toEqual or toBeCalledWith instead of a literal value.

    Optionally, pass a type for the elements as a generic argument.

  • num: number,
    numDigits?: number
    ): any;

    Matches a number close to the provided value. Use it when comparing floating point numbers in object properties or array items. To compare a number directly, use .toBeCloseTo instead.

    The optional numDigits argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion is Math.abs(expected - received) < 0.005 (that is, 10 ** -2 / 2).

  • obj: object
    ): any;

    Matches any object that recursively matches the provided keys.

    Optionally, pass a type for the object as a generic argument. This ensures that the object contains the desired structure.

  • str: string | String
    ): any;

    Matches any received string that contains the exact expected string

  • regex: string | String | RegExp
    ): any;

    Matches any received string that matches the regular expression.

    A string is the source of a regular expression, as in new RegExp(regex). It is not searched for literally, and an invalid one throws a SyntaxError. To look for a literal string, use expect.stringContaining.

    expect({ id: "user-42" }).toEqual({ id: expect.stringMatching(/^user-\d+$/) });
expect({ id: "user-42" }).toEqual({ id: expect.stringMatching("^user-\\d+$") });
  • predicate: (value: any) => unknown,
    message?: string
    ): any;

    Matches any received value for which predicate returns a truthy value. Use it inside toEqual or toBeCalledWith instead of a literal value.

    message describes the predicate. It has no effect on the match. It is printed after the predicate wherever the matcher is printed, such as in a failure message or a snapshot.

    const isOdd = (n: number) => n % 2 === 1;
expect({ count: 3 }).toEqual({ count: expect.toSatisfy(isOdd) });
expect({ count: 3 }).toEqual({ count: expect.toSatisfy(isOdd, "an odd number") });