Symbol

CustomMatchersDetected

type CustomMatchersDetected = Omit<Matchers<unknown>, keyof MatchersBuiltin<unknown>> & Omit<AsymmetricMatchers, keyof AsymmetricMatchersBuiltin>

All non-builtin matchers and asymmetric matchers that have been type-registered through declaration merging

Referenced types

interface Matchers<T = unknown>

You can extend this interface with declaration merging, in order 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. If you know how to test something, .not lets you test its opposite.
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);
lastCalledWith(...expected: unknown[]): void
Ensure that a mock function is called with specific arguments for the nth call.
nthCalledWith(n: number, ...expected: unknown[]): void
Ensure that a mock function is called with specific arguments for the nth call.
toBe(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()
toBeArray(): void
Asserts that a value is a array.
expect([1]).toBeArray(); expect(new Array(1)).toBeArray(); expect({}).not.toBeArray();
toBeArrayOfSize(size: number): void
Asserts that a value is a 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 an exact number of times.
toBeCalledTimes(expected: number): void
Ensure that a mock function is called with specific arguments.
toBeCalledWith(...expected: unknown[]): void
Ensure that a mock function is called with specific arguments.
toBeCloseTo(expected: number, numDigits?: number): void
Asserts that value is close to the expected by floating point precision.
For example, the following fails because arithmetic on decimal (base 10) values often have 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. (e.g. 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();
toBeEmptyObject(): void
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(true).toBeTruthy(); expect(1).toBeTruthy(); expect({}).toBeTruthy();
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();
toBeGreaterThan(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
toBeGreaterThanOrEqual(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);
toBeInstanceOf(value: unknown): void
Asserts that the expected value is an instance of value
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();
toBeLessThan(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
toBeLessThanOrEqual(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();
toBeOneOf(expected: unknown[] | Iterable<unknown, any, any>): void
Asserts that the value is deep 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]));
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();
toBeTypeOf(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();
toBeWithin(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)
toContain(expected: unknown): 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");
toContainAllKeys(expected: unknown): 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']);
toContainAllValues(expected: unknown): void
Asserts that an object contain 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']);
toContainAnyKeys(expected: unknown): void
Asserts that an object contains at least one of the provided keys. 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' }).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']);
toContainAnyValues(expected: unknown): void
Asserts that an object contain any provided value.
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']);
toContainEqual(expected: unknown): void
Asserts that a value contains and equals what is expected.
This matcher will perform a deep equality check for members of arrays, rather than checking for object identity.
@param expected
the expected value
expect([{ a: 1 }]).toContainEqual({ a: 1 }); expect([{ a: 1 }]).not.toContainEqual({ a: 2 });
toContainKey(expected: unknown): 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');
toContainKeys(expected: unknown): 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']);
toContainValue(expected: unknown): void
Asserts that an object contain the provided value.
The 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" }]);
toContainValues(expected: unknown): void
Asserts that an object contain the provided value.
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']);
toEndWith(expected: string): void
Asserts that a value ends with a string.
@param expected
the string to end with
toEqual(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 });
toEqualIgnoringWhitespace(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 ");
toHaveBeenCalled(): void
Ensures that a mock function is called.
toHaveBeenCalledTimes(expected: number): void
Ensures that a mock function is called an exact number of times.
toHaveBeenCalledWith(...expected: unknown[]): void
Ensure that a mock function is called with specific arguments.
toHaveBeenLastCalledWith(...expected: unknown[]): void
Ensure that a mock function is called with specific arguments for the last call.
toHaveBeenNthCalledWith(n: number, ...expected: unknown[]): void
Ensure that a mock function is called with specific arguments for the nth call.
toHaveLength(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(4);
toHaveProperty(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);
toHaveReturned(): void
Ensures that a mock function has returned successfully at least once.
A promise that is unfulfilled will be considered a failure. If the function threw an error, it will be considered a failure.
toHaveReturnedTimes(times: number): void
Ensures that a mock function has returned successfully at times times.
A promise that is unfulfilled will be considered a failure. If the function threw an error, it will be considered a failure.
toInclude(expected: string): void
Asserts that a value includes a string.
For non-string values, use toContain() instead.
@param expected
the expected substring
toIncludeRepeated(expected: string, times: number): void
Asserts that a value includes a string {times} times.
@param expected
the expected substring
@param times
the number of times the substring should occur
toMatch(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");
toMatchInlineSnapshot(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"`);
toMatchInlineSnapshot(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>, } `);
toMatchObject(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 });
toMatchSnapshot(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');
toMatchSnapshot(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) });
toSatisfy(predicate: (value: T) => boolean): void
Checks whether a value satisfies a custom condition.
@param predicate
The custom condition to be satisfied. It should be a function that takes a value as an argument (in this case the value from expect) and returns a boolean.
expect(1).toSatisfy((val) => val > 0); expect("foo").toSatisfy((val) => val === "foo"); expect("bar").not.toSatisfy((val) => val === "bun");
toStartWith(expected: string): void
Asserts that a value starts with a string.
@param expected
the string to start with
toStrictEqual(expected: T): void
Asserts that a value is deeply and strictly equal to what is expected.
There are two key differences from toEqual():
It checks that the class is the same.
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
toThrow(expected?: unknown): void
Asserts that a function throws an error.
If expected is a string or RegExp, it will check the message property.
If expected is an Error object, it will check the name and message properties.
If expected is an Error constructor, it will check the class of the Error.
If expected is not provided, it will check if anything has 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();
toThrowError(expected?: unknown): void
Asserts that a function throws an error.
If expected is a string or RegExp, it will check the message property.
If expected is an Error object, it will check the name and message properties.
If expected is an Error constructor, it will check the class of the Error.
If expected is not provided, it will check if anything has 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();
toThrowErrorMatchingInlineSnapshot(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!"`);
toThrowErrorMatchingSnapshot(hint?: string): void
Asserts that a function throws an error matching the most recent snapshot.
function fail() { throw new Error("Oops!"); } expect(fail).toThrowErrorMatchingSnapshot(); expect(fail).toThrowErrorMatchingSnapshot("This one should say Oops!");

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 {}
}

any(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.
closeTo(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).
objectContaining(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.
stringContaining(str: string | String): any
Matches any received string that contains the exact expected string
stringMatching(regex: string | String | RegExp): any
Matches any string that contains the exact provided string