interface

test.Matchers

interface Matchers<T = unknown>

Extend this interface with declaration merging to add type support for custom 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 {}
}
  • fail: (message?: string) => void

    Assertion which fails.

    expect().fail();
expect().fail("message is optional");
expect().not.fail();
expect().not.fail("hi");
  • not: Matchers<unknown>

    Negates the result of a subsequent assertion.

    expect(1).not.toBe(0);
expect(null).not.toBeNull();
  • pass: (message?: string) => void

    Assertion which passes.

    expect().pass();
expect().pass("message is optional");
expect().not.pass();
expect().not.pass("hi");
  • rejects: Matchers<unknown>

    Expects the value to be a promise that rejects.

    expect(Promise.reject("error")).rejects.toBe("error");
  • resolves: Matchers<Awaited<T>>

    Expects the value to be a promise that resolves.

    expect(Promise.resolve(1)).resolves.toBe(1);
  • ...expected: unknown[]
    ): void;

    Ensure that a mock function is called with specific arguments for the last call.

  • n: number,
    ...expected: unknown[]
    ): void;

    Ensure that a mock function is called with specific arguments for the nth call.

  • expected: T
    ): void;

    Asserts that a value equals what is expected.

    • For non-primitive values, like objects and arrays, use toEqual() instead.
    • For floating-point numbers, use toBeCloseTo() instead.
    @param expected

    the expected value

    expect(100 + 23).toBe(123);
expect("d" + "og").toBe("dog");
expect([123]).toBe([123]); // fail, use toEqual()
expect(3 + 0.14).toBe(3.14); // fail, use toBeCloseTo()

// TypeScript errors:
expect("hello").toBe(3.14); // typescript error + fail
expect("hello").toBe<number>(3.14); // no typescript error, but still fails
    toBe<X = T>(
    expected: NoInfer<X>
    ): void;
  • toBeArray(): void;

    Asserts that a value is an array.

    expect([1]).toBeArray();
expect(new Array(1)).toBeArray();
expect({}).not.toBeArray();
  • size: number
    ): void;

    Asserts that a value is an array of a certain length.

    expect([]).toBeArrayOfSize(0);
expect([1]).toBeArrayOfSize(1);
expect(new Array(1)).toBeArrayOfSize(1);
expect({}).not.toBeArrayOfSize(0);
  • toBeBoolean(): void;

    Asserts that a value is a boolean.

    expect(true).toBeBoolean();
expect(false).toBeBoolean();
expect(null).not.toBeBoolean();
expect(0).not.toBeBoolean();
  • toBeCalled(): void;

    Ensures that a mock function is called.

  • expected: number
    ): void;

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

  • ...expected: unknown[]
    ): void;

    Ensure that a mock function is called with specific arguments.

  • expected: number,
    numDigits?: number
    ): void;

    Asserts that a value is close to the expected value, within floating point precision.

    For example, the following fails because arithmetic on decimal (base 10) values often has rounding errors in limited precision binary (base 2) representation.

    @param expected

    the expected value

    @param numDigits

    the number of digits to check after the decimal point. Default is 2

    expect(0.2 + 0.1).toBe(0.3); // fails

Use `toBeCloseTo` to compare floating point numbers for approximate equality.
  • toBeDate(): void;

    Asserts that a value is a Date object.

    To check if a date is valid, use toBeValidDate() instead.

    expect(new Date()).toBeDate();
expect(new Date(null)).toBeDate();
expect("2020-03-01").not.toBeDate();
  • toBeDefined(): void;

    Asserts that a value is defined (that is, not undefined).

    expect(true).toBeDefined();
expect(undefined).toBeDefined(); // fail
  • toBeEmpty(): void;

    Asserts that a value is empty.

    expect("").toBeEmpty();
expect([]).toBeEmpty();
expect({}).toBeEmpty();
expect(new Set()).toBeEmpty();

  • Asserts that a value is an empty object.

    expect({}).toBeEmptyObject();
expect({ a: 'hello' }).not.toBeEmptyObject();
  • toBeEven(): void;

    Asserts that a number is even.

    expect(2).toBeEven();
expect(1).not.toBeEven();
  • toBeFalse(): void;

    Asserts that a value is false.

    expect(false).toBeFalse();
expect(true).not.toBeFalse();
expect(0).not.toBeFalse();
  • toBeFalsy(): void;

    Asserts that a value is "falsy".

    To assert that a value equals false, use toBe(false) instead.

    expect(false).toBeFalsy();
expect(0).toBeFalsy();
expect("").toBeFalsy();
  • toBeFinite(): void;

    Asserts that a value is a number, and is not NaN or Infinity.

    expect(1).toBeFinite();
expect(3.14).toBeFinite();
expect(NaN).not.toBeFinite();
expect(Infinity).not.toBeFinite();
  • toBeFunction(): void;

    Asserts that a value is a function.

    expect(() => {}).toBeFunction();
  • expected: number | bigint
    ): void;

    Asserts that a value is a number and is greater than the expected value.

    @param expected

    the expected number

    expect(1).toBeGreaterThan(0);
expect(3.14).toBeGreaterThan(3);
expect(9).toBeGreaterThan(9); // fail
  • expected: number | bigint
    ): void;

    Asserts that a value is a number and is greater than or equal to the expected value.

    @param expected

    the expected number

    expect(1).toBeGreaterThanOrEqual(0);
expect(3.14).toBeGreaterThanOrEqual(3);
expect(9).toBeGreaterThanOrEqual(9);
  • value: unknown
    ): void;

    Asserts that a value is an instance of the given class or constructor.

    expect([]).toBeInstanceOf(Array);
expect(null).toBeInstanceOf(Array); // fail
  • toBeInteger(): void;

    Asserts that a value is a number, and is an integer.

    expect(1).toBeInteger();
expect(3.14).not.toBeInteger();
expect(NaN).not.toBeInteger();
  • expected: number | bigint
    ): void;

    Asserts that a value is a number and is less than the expected value.

    @param expected

    the expected number

    expect(-1).toBeLessThan(0);
expect(3).toBeLessThan(3.14);
expect(9).toBeLessThan(9); // fail
  • expected: number | bigint
    ): void;

    Asserts that a value is a number and is less than or equal to the expected value.

    @param expected

    the expected number

    expect(-1).toBeLessThanOrEqual(0);
expect(3).toBeLessThanOrEqual(3.14);
expect(9).toBeLessThanOrEqual(9);
  • toBeNaN(): void;

    Asserts that a value is NaN.

    Same as using Number.isNaN().

    expect(NaN).toBeNaN();
expect(Infinity).toBeNaN(); // fail
expect("notanumber").toBeNaN(); // fail
  • toBeNegative(): void;

    Asserts that a value is a negative number.

    expect(-3.14).toBeNegative();
expect(1).not.toBeNegative();
expect(NaN).not.toBeNegative();
  • toBeNil(): void;

    Asserts that a value is null or undefined.

    expect(null).toBeNil();
expect(undefined).toBeNil();
  • toBeNull(): void;

    Asserts that a value is null.

    expect(null).toBeNull();
expect(undefined).toBeNull(); // fail
  • toBeNumber(): void;

    Asserts that a value is a number.

    expect(1).toBeNumber();
expect(3.14).toBeNumber();
expect(NaN).toBeNumber();
expect(BigInt(1)).not.toBeNumber();
  • toBeObject(): void;

    Asserts that a value is an object.

    expect({}).toBeObject();
expect("notAnObject").not.toBeObject();
expect(NaN).not.toBeObject();
  • toBeOdd(): void;

    Asserts that a number is odd.

    expect(1).toBeOdd();
expect(2).not.toBeOdd();
  • expected: Iterable<T>
    ): void;

    Asserts that the value is deeply equal to an element in the expected array.

    The value must be an array or iterable, which includes strings.

    @param expected

    the expected value

    expect(1).toBeOneOf([1,2,3]);
expect("foo").toBeOneOf(["foo", "bar"]);
expect(true).toBeOneOf(new Set([true]));
    toBeOneOf<X = T>(
    expected: NoInfer<Iterable<X, any, any>>
    ): void;
  • toBePositive(): void;

    Asserts that a value is a positive number.

    expect(1).toBePositive();
expect(-3.14).not.toBePositive();
expect(NaN).not.toBePositive();
  • toBeString(): void;

    Asserts that a value is a string.

    expect("foo").toBeString();
expect(new String("bar")).toBeString();
expect(123).not.toBeString();
  • toBeSymbol(): void;

    Asserts that a value is a symbol.

    expect(Symbol("foo")).toBeSymbol();
expect("foo").not.toBeSymbol();
  • toBeTrue(): void;

    Asserts that a value is true.

    expect(true).toBeTrue();
expect(false).not.toBeTrue();
expect(1).not.toBeTrue();
  • toBeTruthy(): void;

    Asserts that a value is "truthy".

    To assert that a value equals true, use toBe(true) instead.

    expect(true).toBeTruthy();
expect(1).toBeTruthy();
expect({}).toBeTruthy();
  • type: 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function'
    ): void;

    Asserts that a value matches a specific type.

    expect(1).toBeTypeOf("number");
expect("hello").toBeTypeOf("string");
expect([]).not.toBeTypeOf("boolean");
  • toBeUndefined(): void;

    Asserts that a value is undefined.

    expect(undefined).toBeUndefined();
expect(null).toBeUndefined(); // fail
  • toBeValidDate(): void;

    Asserts that a value is a valid Date object.

    expect(new Date()).toBeValidDate();
expect(new Date(null)).not.toBeValidDate();
expect("2020-03-01").not.toBeValidDate();
  • start: number,
    end: number
    ): void;

    Asserts that a value is a number between a start and end value.

    @param start

    the start number (inclusive)

    @param end

    the end number (exclusive)

  • expected: T extends Iterable<U, any, any> ? U : T
    ): void;

    Asserts that a value contains what is expected.

    The value must be an array or iterable, which includes strings.

    @param expected

    the expected value

    expect([1, 2, 3]).toContain(1);
expect(new Set([true])).toContain(true);
expect("hello").toContain("o");
    toContain<X = T>(
    expected: NoInfer<X extends Iterable<U, any, any> ? U : X>
    ): void;
  • expected: IfNeverThenElse<keyof T, PropertyKey>[]
    ): void;

    Asserts that an object contains all the provided keys.

    The value must be an object.

    @param expected

    the expected value

    expect({ a: 'hello', b: 'world' }).toContainAllKeys(['a','b']);
expect({ a: 'hello', b: 'world' }).toContainAllKeys(['b','a']);
expect({ 1: 'hello', b: 'world' }).toContainAllKeys([1,'b']);
expect({ a: 'hello', b: 'world' }).not.toContainAllKeys(['c']);
expect({ a: 'hello', b: 'world' }).not.toContainAllKeys(['a']);
    expected: IfNeverThenElse<NoInfer<keyof X>, PropertyKey>[]
    ): void;
  • expected: unknown[]
    ): void;

    Asserts that an object contains all the provided values.

    The value must be an object.

    @param expected

    the expected value

    const o = { a: 'foo', b: 'bar', c: 'baz' };
expect(o).toContainAllValues(['foo', 'bar', 'baz']);
expect(o).toContainAllValues(['baz', 'bar', 'foo']);
expect(o).not.toContainAllValues(['bar', 'foo']);
  • expected: IfNeverThenElse<keyof T, PropertyKey>[]
    ): void;

    Asserts that an object contains at least one of the provided keys.

    The value must be an object.

    @param expected

    the expected value

    expect({ a: 'hello', b: 'world' }).toContainAnyKeys(['a']);
expect({ a: 'hello', b: 'world' }).toContainAnyKeys(['b']);
expect({ a: 'hello', b: 'world' }).toContainAnyKeys(['b', 'c']);
expect({ a: 'hello', b: 'world' }).not.toContainAnyKeys(['c']);
    expected: IfNeverThenElse<NoInfer<keyof X>, PropertyKey>[]
    ): void;
  • expected: unknown[]
    ): void;

    Asserts that an object contains any of the provided values.

    The value must be an object.

    @param expected

    the expected value

    const o = { a: 'foo', b: 'bar', c: 'baz' };
expect(o).toContainAnyValues(['qux', 'foo']);
expect(o).toContainAnyValues(['qux', 'bar']);
expect(o).toContainAnyValues(['qux', 'baz']);
expect(o).not.toContainAnyValues(['qux']);
  • expected: T extends Iterable<U, any, any> ? U : T
    ): void;

    Asserts that a value contains and equals what is expected.

    This matcher performs a deep equality check on array members, rather than checking for object identity.

    @param expected

    the expected value

    expect([{ a: 1 }]).toContainEqual({ a: 1 });
expect([{ a: 1 }]).not.toContainEqual({ a: 2 });
    expected: NoInfer<X extends Iterable<U, any, any> ? U : X>
    ): void;
  • expected: IfNeverThenElse<keyof T, PropertyKey>
    ): void;

    Asserts that an object contains a key.

    The value must be an object.

    @param expected

    the expected value

    expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKey('a');
expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKey('b');
expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKey('c');
expect({ a: 'foo', b: 'bar', c: 'baz' }).not.toContainKey('d');
    toContainKey<X = T>(
    expected: IfNeverThenElse<NoInfer<keyof X>, PropertyKey>
    ): void;
  • expected: IfNeverThenElse<keyof T, PropertyKey>[]
    ): void;

    Asserts that an object contains all the provided keys.

    @param expected

    the expected value

    expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKeys(['a', 'b']);
expect({ a: 'foo', b: 'bar', c: 'baz' }).toContainKeys(['a', 'b', 'c']);
expect({ a: 'foo', b: 'bar', c: 'baz' }).not.toContainKeys(['a', 'b', 'e']);
    expected: IfNeverThenElse<NoInfer<keyof X>, PropertyKey>[]
    ): void;
  • expected: unknown
    ): void;

    Asserts that an object contains the provided value.

    This check is deep: it looks through child properties to find the expected value.

    The input value must be an object.

    @param expected

    the expected value

    const shallow = { hello: "world" };
const deep = { message: shallow };
const deepArray = { message: [shallow] };
const o = { a: "foo", b: [1, "hello", true], c: "baz" };

expect(shallow).toContainValue("world");
expect({ foo: false }).toContainValue(false);
expect(deep).toContainValue({ hello: "world" });
expect(deepArray).toContainValue([{ hello: "world" }]);

expect(o).toContainValue("foo", "barr");
expect(o).toContainValue([1, "hello", true]);
expect(o).not.toContainValue("qux");

// NOT
expect(shallow).not.toContainValue("foo");
expect(deep).not.toContainValue({ foo: "bar" });
expect(deepArray).not.toContainValue([{ foo: "bar" }]);
  • expected: unknown[]
    ): void;

    Asserts that an object contains the provided values.

    This is the same as toContainValue, but accepts an array of values instead.

    The value must be an object.

    @param expected

    the expected value

    const o = { a: 'foo', b: 'bar', c: 'baz' };
expect(o).toContainValues(['foo']);
expect(o).toContainValues(['baz', 'bar']);
expect(o).not.toContainValues(['qux', 'foo']);
  • expected: string
    ): void;

    Asserts that a value ends with a string.

    @param expected

    the string to end with

  • expected: T
    ): void;

    Asserts that a value is deeply equal to what is expected.

    @param expected

    the expected value

    expect(100 + 23).toBe(123);
expect("d" + "og").toBe("dog");
expect([456]).toEqual([456]);
expect({ value: 1 }).toEqual({ value: 1 });
    toEqual<X = T>(
    expected: NoInfer<X>
    ): void;
  • expected: string
    ): void;

    Asserts that a value is equal to the expected string, ignoring any whitespace.

    @param expected

    the expected string

    expect(" foo ").toEqualIgnoringWhitespace("foo");
expect("bar").toEqualIgnoringWhitespace(" bar ");

  • Ensures that a mock function is called.

  • expected: number
    ): void;

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

  • ...expected: unknown[]
    ): void;

    Ensure that a mock function is called with specific arguments.

  • ...expected: unknown[]
    ): void;

    Ensure that a mock function is called with specific arguments for the last call.

  • n: number,
    ...expected: unknown[]
    ): void;

    Ensure that a mock function is called with specific arguments for the nth call.

  • expected: unknown
    ): void;

    Ensures that a mock function has returned a specific value on its last invocation. This matcher uses deep equality, like toEqual(), and supports asymmetric matchers.

  • length: number
    ): void;

    Asserts that a value has a .length property that is equal to the expected length.

    @param length

    the expected length

    expect([]).toHaveLength(0);
expect("hello").toHaveLength(5);
  • n: number,
    expected: unknown
    ): void;

    Ensures that a mock function has returned a specific value on the nth invocation. This matcher uses deep equality, like toEqual(), and supports asymmetric matchers.

    @param n

    The 1-based index of the function call

    @param expected

    The expected return value

  • keyPath: string | number | string | number[],
    value?: unknown
    ): void;

    Asserts that a value has a property with the expected name, and value if provided.

    @param keyPath

    the expected property name or path, or an index

    @param value

    the expected property value, if provided

    expect(new Set()).toHaveProperty("size");
expect(new Uint8Array()).toHaveProperty("byteLength", 0);
expect({ kitchen: { area: 20 }}).toHaveProperty("kitchen.area", 20);
expect({ kitchen: { area: 20 }}).toHaveProperty(["kitchen", "area"], 20);

  • Ensures that a mock function has returned successfully at least once.

    An unfulfilled promise counts as a failure, as does a thrown error.

  • times: number
    ): void;

    Ensures that a mock function has returned successfully times times.

    An unfulfilled promise counts as a failure, as does a thrown error.

  • expected: unknown
    ): void;

    Ensures that a mock function has returned a specific value. This matcher uses deep equality, like toEqual(), and supports asymmetric matchers.

  • expected: string
    ): void;

    Asserts that a value includes a string.

    For non-string values, use toContain() instead.

    @param expected

    the expected substring

  • expected: string,
    times: number
    ): void;

    Asserts that a value includes a string the given number of times.

    @param expected

    the expected substring

    @param times

    the number of times the substring should occur

  • expected: string | RegExp
    ): void;

    Asserts that a value matches a regular expression or includes a substring.

    @param expected

    the expected substring or pattern.

    expect("dog").toMatch(/dog/);
expect("dog").toMatch("og");
  • value?: string
    ): void;

    Asserts that a value matches the most recent inline snapshot.

    @param value

    The latest automatically-updated snapshot value.

    expect("Hello").toMatchInlineSnapshot();
expect("Hello").toMatchInlineSnapshot(`"Hello"`);
    propertyMatchers?: object,
    value?: string
    ): void;

    Asserts that a value matches the most recent inline snapshot.

    @param propertyMatchers

    Object containing properties to match against the value.

    @param value

    The latest automatically-updated snapshot value.

    expect({ c: new Date() }).toMatchInlineSnapshot({ c: expect.any(Date) });
expect({ c: new Date() }).toMatchInlineSnapshot({ c: expect.any(Date) }, `
{
  "v": Any<Date>,
}
`);
  • subset: object
    ): void;

    Asserts that an object matches a subset of properties.

    @param subset

    Subset of properties to match with.

    expect({ a: 1, b: 2 }).toMatchObject({ b: 2 });
expect({ c: new Date(), d: 2 }).toMatchObject({ d: 2 });
  • hint?: string
    ): void;

    Asserts that a value matches the most recent snapshot.

    @param hint

    Hint used to identify the snapshot in the snapshot file.

    expect([1, 2, 3]).toMatchSnapshot('hint message');
    propertyMatchers?: object,
    hint?: string
    ): void;

    Asserts that a value matches the most recent snapshot.

    @param propertyMatchers

    Object containing properties to match against the value.

    @param hint

    Hint used to identify the snapshot in the snapshot file.

    expect([1, 2, 3]).toMatchSnapshot();
expect({ a: 1, b: 2 }).toMatchSnapshot({ a: 1 });
expect({ c: new Date() }).toMatchSnapshot({ c: expect.any(Date) });
  • predicate: (value: T) => boolean
    ): void;

    Asserts that a value satisfies a custom condition.

    @param predicate

    a function that receives the value passed to expect and returns a boolean

    expect(1).toSatisfy((val) => val > 0);
expect("foo").toSatisfy((val) => val === "foo");
expect("bar").not.toSatisfy((val) => val === "bun");
  • expected: string
    ): void;

    Asserts that a value starts with a string.

    @param expected

    the string to start with

  • expected: T
    ): void;

    Asserts that a value is deeply and strictly equal to what is expected.

    There are two key differences from toEqual():

    1. It checks that the class is the same.
    2. It checks that undefined values match as well.
    @param expected

    the expected value

    class Dog {
  type = "dog";
}
const actual = new Dog();
expect(actual).toStrictEqual(new Dog());
expect(actual).toStrictEqual({ type: "dog" }); // fail
    expected: NoInfer<X>
    ): void;
  • expected?: unknown
    ): void;

    Asserts that a function throws an error.

    • If expected is a string or RegExp, it checks the message property.
    • If expected is an Error object, it checks the name and message properties.
    • If expected is an Error constructor, it checks the class of the Error.
    • If expected is not provided, it checks that anything was thrown.
    @param expected

    the expected error, error message, or error pattern

    function fail() {
  throw new Error("Oops!");
}
expect(fail).toThrow("Oops!");
expect(fail).toThrow(/oops/i);
expect(fail).toThrow(Error);
expect(fail).toThrow();
  • expected?: unknown
    ): void;

    Asserts that a function throws an error.

    • If expected is a string or RegExp, it checks the message property.
    • If expected is an Error object, it checks the name and message properties.
    • If expected is an Error constructor, it checks the class of the Error.
    • If expected is not provided, it checks that anything was thrown.
    @param expected

    the expected error, error message, or error pattern

    function fail() {
  throw new Error("Oops!");
}
expect(fail).toThrowError("Oops!");
expect(fail).toThrowError(/oops/i);
expect(fail).toThrowError(Error);
expect(fail).toThrowError();
  • value?: string
    ): void;

    Asserts that a function throws an error matching the most recent snapshot.

    @param value

    The latest automatically-updated snapshot value.

    function fail() {
  throw new Error("Oops!");
}
expect(fail).toThrowErrorMatchingInlineSnapshot();
expect(fail).toThrowErrorMatchingInlineSnapshot(`"Oops!"`);
  • hint?: string
    ): void;

    Asserts that a function throws an error matching the most recent snapshot.

    @param hint

    Hint used to identify the snapshot in the snapshot file.

    function fail() {
  throw new Error("Oops!");
}
expect(fail).toThrowErrorMatchingSnapshot();
expect(fail).toThrowErrorMatchingSnapshot("This one should say Oops!");