DocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

interface

test.AsymmetricMatchers

interface AsymmetricMatchers

You can extend this interface with declaration merging, in order 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. You can 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. You can use it inside toEqual or toBeCalledWith instead of a literal value. For example, if you want 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. You can use it inside toEqual or toBeCalledWith instead of a literal value.

    Optionally, you can provide a type for the elements via a generic.

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

    Useful when comparing floating point numbers in object properties or array item. If you need to compare a number, 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. This is often handy in conjunction with other asymmetric matchers.

    Optionally, you can provide a type for the object via a generic. 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 string that contains the exact provided string