bun:test module | API Reference | Bun

Constructs the type of a mock function, e.g. the return type of jest.fn().

Constructs the type of a replaced property.

Constructs the type of a spied class or function.

Constructs the type of a spied class.

Constructs the type of a spied function.

Constructs the type of a spied getter.

Constructs the type of a spied setter.

Describes a group of related tests.

function sum(a, b) {
return a + b;
}
describe("sum()", () => {
test("can sum two values", () => {
expect(sum(1, 1)).toBe(2);
});
});

Asserts that a value matches some criteria.

expect(1 + 1).toBe(2);
expect([1,2,3]).toContain(2);
expect(null).toBeNull();

Runs a test.

test("can check if using Bun", () => {
expect(Bun).toBeDefined();
});

test("can make a fetch() request", async () => {
const response = await fetch("https://example.com/");
expect(response.ok).toBe(true);
});

Vitest-compatible mocking utilities Provides Vitest-style mocking API for easier migration from Vitest to Bun

Skips a group of related tests.

This is equivalent to calling describe.skip().

Skips a test.

This is equivalent to calling test.skip().

Runs a function, once, after all the tests.

This is useful for running clean up tasks, like closing a socket or deleting temporary files.

the function to run

let database;
afterAll(async () => {
if (database) {
await database.close();
}
});

Runs a function after each test.

This is useful for running clean up tasks, like closing a socket or deleting temporary files.

the function to run

Runs a function, once, before all the tests.

This is useful for running set up tasks, like initializing a global variable or connecting to a database.

If this function throws, tests will not run in this file.

the function to run

let database;
beforeAll(async () => {
database = await connect("localhost");
});

Runs a function before each test.

This is useful for running set up tasks, like initializing a global variable or connecting to a database.

If this function throws, the test will not run.

the function to run

Runs a function after a test finishes, including after all afterEach hooks.

This is useful for cleanup tasks that need to run at the very end of a test, after all other hooks have completed.

Can only be called inside a test, not in describe blocks.

the function to run

test("my test", () => {
onTestFinished(() => {
// This runs after all afterEach hooks
console.log("Test finished!");
});
});

Sets the default timeout for all tests in the current file. If a test specifies a timeout, it will override this value. The default timeout is 5000ms (5 seconds).

the number of milliseconds for the default timeout

Control the system time used by:

In the future, we may add support for more functions, but we haven't done that yet.

The time to set the system time to. If not provided, the system time will be reset.

this

Create a spy on an object property or method

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 MatchersT> extends MyCustomMatchers {}
interface AsymmetricMatchers extends MyCustomMatchers {}
}

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));
});

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());
});

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.

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) (that is, 10 ** -2 / 2).

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.

Matches any received string that contains the exact expected string

Matches any string that contains the exact provided string

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));
});

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());
});

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.

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) (that is, 10 ** -2 / 2).

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.

Matches any received string that contains the exact expected string

Matches any string that contains the exact provided string

Describes a group of related tests.

function sum(a, b) {
return a + b;
}
describe("sum()", () => {
test("can sum two values", () => {
expect(sum(1, 1)).toBe(2);
});
});

Marks this group of tests to be executed concurrently.

Skips all other tests, except this group of tests.

Marks this group of tests to be executed serially (one after another), even when the --concurrent flag is used.

Skips this group of tests.

Marks this group of tests as to be written or to be fixed.

Runs this group of tests, only if condition is true.

This is the opposite of describe.skipIf().

if these tests should run

Skips this group of tests, if condition is true.

if these tests should be skipped

Marks this group of tests as to be written or to be fixed, if condition is true.

if these tests should be skipped

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 MatchersT> extends MyCustomMatchers {}
interface AsymmetricMatchers extends MyCustomMatchers {}
}

Access to negated asymmetric matchers.

expect("abc").toEqual(expect.stringContaining("abc")); // will pass
expect("abc").toEqual(expect.not.stringContaining("abc")); // will fail

Create an asymmetric matcher for a promise rejected value.

expect(Promise.reject("error")).toEqual(expect.rejectsTo.stringContaining("error")); // will pass
expect(Promise.resolve("error")).toEqual(expect.rejectsTo.stringContaining("error")); // will fail
expect("error").toEqual(expect.rejectsTo.stringContaining("error")); // will fail

Create an asymmetric matcher for a promise resolved value.

expect(Promise.resolve("value")).toEqual(expect.resolvesTo.stringContaining("value")); // will pass
expect(Promise.reject("value")).toEqual(expect.resolvesTo.stringContaining("value")); // will fail
expect("value").toEqual(expect.resolvesTo.stringContaining("value")); // will fail

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));
});

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());
});

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.

Ensures that a specific number of assertions are made

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) (that is, 10 ** -2 / 2).

Register new custom matchers.

An object containing the matchers to register, where each key is the matcher name, and its value the implementation function. The function must satisfy: (actualValue, ...matcherInstantiationArguments) => { pass: true|false, message: () => string }

expect.extend({
toBeWithinRange(actual, min, max) {
if (typeof actual !== 'number' || typeof min !== 'number' || typeof max !== 'number')
throw new Error('Invalid usage');
const pass = actual >= min && actual max;
return {
pass: pass,
message: () => `expected ${this.utils.printReceived(actual)} ` +
(pass ? `not to be`: `to be`) + ` within range ${this.utils.printExpected(`${min} .. ${max}`)}`,
};
},
});

test('some test', () => {
expect(50).toBeWithinRange(0, 100); // will pass
expect(50).toBeWithinRange(100, 200); // will fail
expect(50).toBe(expect.toBeWithinRange(0, 100)); // will pass
expect(50).toBe(expect.not.toBeWithinRange(100, 200)); // will pass
});

Ensures that an assertion is made

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.

Matches any received string that contains the exact expected string

Matches any string that contains the exact provided string

Throw an error if this function is called.

Optional message to display if the test fails

never

import { expect, test } from "bun:test";

test("!!abc!! is not a module", () => {
try {
require("!!abc!!");
expect.unreachable();
} catch(e) {
expect(e.name).not.toBe("UnreachableError");
}
});

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 MatchersT> extends MyCustomMatchers {}
interface AsymmetricMatchers extends MyCustomMatchers {}
}

Assertion which fails.

expect().fail();
expect().fail("message is optional");
expect().not.fail();
expect().not.fail("hi");

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();

Assertion which passes.

expect().pass();
expect().pass("message is optional");
expect().not.pass();
expect().not.pass("hi");

Expects the value to be a promise that rejects.

expect(Promise.reject("error")).rejects.toBe("error");

Expects the value to be a promise that resolves.

expect(Promise.resolve(1)).resolves.toBe(1);

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

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

Asserts that a value equals what is 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").toBenumber>(3.14); // no typescript error, but still fails

Asserts that a value is a array.

expect([1]).toBeArray();
expect(new Array(1)).toBeArray();
expect({}).not.toBeArray();

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);

Asserts that a value is a boolean.

expect(true).toBeBoolean();
expect(false).toBeBoolean();
expect(null).not.toBeBoolean();
expect(0).not.toBeBoolean();

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

Ensure that a mock function is called with specific arguments.

Ensure that a mock function is called with specific arguments.

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.

the expected value

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.

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();

Asserts that a value is defined. (e.g. is not undefined)

expect(true).toBeDefined();
expect(undefined).toBeDefined(); // fail

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();

Asserts that a number is even.

expect(2).toBeEven();
expect(1).not.toBeEven();

Asserts that a value is false.

expect(false).toBeFalse();
expect(true).not.toBeFalse();
expect(0).not.toBeFalse();

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();

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();

Asserts that a value is a function.

expect(() => {}).toBeFunction();

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

the expected number

expect(1).toBeGreaterThan(0);
expect(3.14).toBeGreaterThan(3);
expect(9).toBeGreaterThan(9); // fail

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

the expected number

expect(1).toBeGreaterThanOrEqual(0);
expect(3.14).toBeGreaterThanOrEqual(3);
expect(9).toBeGreaterThanOrEqual(9);

Asserts that the expected value is an instance of value

expect([]).toBeInstanceOf(Array);
expect(null).toBeInstanceOf(Array); // fail

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

expect(1).toBeInteger();
expect(3.14).not.toBeInteger();
expect(NaN).not.toBeInteger();

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

the expected number

expect(-1).toBeLessThan(0);
expect(3).toBeLessThan(3.14);
expect(9).toBeLessThan(9); // fail

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

the expected number

expect(-1).toBeLessThanOrEqual(0);
expect(3).toBeLessThanOrEqual(3.14);
expect(9).toBeLessThanOrEqual(9);

Asserts that a value is NaN.

Same as using Number.isNaN().

expect(NaN).toBeNaN();
expect(Infinity).toBeNaN(); // fail
expect("notanumber").toBeNaN(); // fail

Asserts that a value is a negative number.

expect(-3.14).toBeNegative();
expect(1).not.toBeNegative();
expect(NaN).not.toBeNegative();

Asserts that a value is null or undefined.

expect(null).toBeNil();
expect(undefined).toBeNil();

Asserts that a value is null.

expect(null).toBeNull();
expect(undefined).toBeNull(); // fail

Asserts that a value is a number.

expect(1).toBeNumber();
expect(3.14).toBeNumber();
expect(NaN).toBeNumber();
expect(BigInt(1)).not.toBeNumber();

Asserts that a value is an object.

expect({}).toBeObject();
expect("notAnObject").not.toBeObject();
expect(NaN).not.toBeObject();

Asserts that a number is odd.

expect(1).toBeOdd();
expect(2).not.toBeOdd();

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.

the expected value

expect(1).toBeOneOf([1,2,3]);
expect("foo").toBeOneOf(["foo", "bar"]);
expect(true).toBeOneOf(new Set([true]));

Asserts that a value is a positive number.

expect(1).toBePositive();
expect(-3.14).not.toBePositive();
expect(NaN).not.toBePositive();

Asserts that a value is a string.

expect("foo").toBeString();
expect(new String("bar")).toBeString();
expect(123).not.toBeString();

Asserts that a value is a symbol.

expect(Symbol("foo")).toBeSymbol();
expect("foo").not.toBeSymbol();

Asserts that a value is true.

expect(true).toBeTrue();
expect(false).not.toBeTrue();
expect(1).not.toBeTrue();

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();

Asserts that a value matches a specific type.

expect(1).toBeTypeOf("number");
expect("hello").toBeTypeOf("string");
expect([]).not.toBeTypeOf("boolean");

Asserts that a value is undefined.

expect(undefined).toBeUndefined();
expect(null).toBeUndefined(); // fail

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();

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

the start number (inclusive)

the end number (exclusive)

Asserts that a value contains what is expected.

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

the expected value

expect([1, 2, 3]).toContain(1);
expect(new Set([true])).toContain(true);
expect("hello").toContain("o");

Asserts that an object contains all the provided keys.

The value must be an object

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']);

Asserts that an object contain all the provided values.

The value must be an object

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']);

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

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']);

Asserts that an object contain any provided value.

The value must be an object

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']);

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.

the expected value

expect([{ a: 1 }]).toContainEqual({ a: 1 });
expect([{ a: 1 }]).not.toContainEqual({ a: 2 });

Asserts that an object contains a key.

The value must be an object

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');

Asserts that an object contains all the provided keys.

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']);

Asserts that an object contain the provided value.

This method is deep and will look through child properties to find the expected value.

The input value must be an object.

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" }]);

Asserts that an object contain the provided value.

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

The value must be an object

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']);

Asserts that a value ends with a string.

the string to end with

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

the expected value

expect(100 + 23).toBe(123);
expect("d" + "og").toBe("dog");
expect([456]).toEqual([456]);
expect({ value: 1 }).toEqual({ value: 1 });

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

the expected string

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

Ensures that a mock function is called.

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

Ensure that a mock function is called with specific arguments.

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

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

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.

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

the expected length

expect([]).toHaveLength(0);
expect("hello").toHaveLength(4);

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.

The 1-based index of the function call

The expected return value

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

the expected property name or path, or an index

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.

A promise that is unfulfilled will be considered a failure. If the function threw an error, it will be considered a failure.

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.

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

Asserts that a value includes a string.

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

the expected substring

Asserts that a value includes a string {times} times.

the expected substring

the number of times the substring should occur

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

the expected substring or pattern.

expect("dog").toMatch(/dog/);
expect("dog").toMatch("og");

Asserts that a value matches the most recent inline snapshot.

The latest automatically-updated snapshot value.

expect("Hello").toMatchInlineSnapshot();
expect("Hello").toMatchInlineSnapshot(`"Hello"`);

Asserts that a value matches the most recent inline snapshot.

Object containing properties to match against the 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,
}
`);

Asserts that an object matches a subset of properties.

Subset of properties to match with.

expect({ a: 1, b: 2 }).toMatchObject({ b: 2 });
expect({ c: new Date(), d: 2 }).toMatchObject({ d: 2 });

Asserts that a value matches the most recent snapshot.

Hint used to identify the snapshot in the snapshot file.

expect([1, 2, 3]).toMatchSnapshot('hint message');

Asserts that a value matches the most recent snapshot.

Object containing properties to match against the value.

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) });

Checks whether a value satisfies a custom condition.

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");

Asserts that a value starts with a string.

the string to start with

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

There are two key differences from toEqual():

the expected value

class Dog {
type = "dog";
}
const actual = new Dog();
expect(actual).toStrictEqual(new Dog());
expect(actual).toStrictEqual({ type: "dog" }); // fail

Asserts that a function throws an error.

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();

Asserts that a function throws an error.

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();

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

The latest automatically-updated snapshot value.

function fail() {
throw new Error("Oops!");
}
expect(fail).toThrowErrorMatchingInlineSnapshot();
expect(fail).toThrowErrorMatchingInlineSnapshot(`"Oops!"`);

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!");

Assertion which fails.

expect().fail();
expect().fail("message is optional");
expect().not.fail();
expect().not.fail("hi");

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();

Assertion which passes.

expect().pass();
expect().pass("message is optional");
expect().not.pass();
expect().not.pass("hi");

Expects the value to be a promise that rejects.

expect(Promise.reject("error")).rejects.toBe("error");

Expects the value to be a promise that resolves.

expect(Promise.resolve(1)).resolves.toBe(1);

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

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

Asserts that a value equals what is 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").toBenumber>(3.14); // no typescript error, but still fails

Asserts that a value is a array.

expect([1]).toBeArray();
expect(new Array(1)).toBeArray();
expect({}).not.toBeArray();

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);

Asserts that a value is a boolean.

expect(true).toBeBoolean();
expect(false).toBeBoolean();
expect(null).not.toBeBoolean();
expect(0).not.toBeBoolean();

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

Ensure that a mock function is called with specific arguments.

Ensure that a mock function is called with specific arguments.

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.

the expected value

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.

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();

Asserts that a value is defined. (e.g. is not undefined)

expect(true).toBeDefined();
expect(undefined).toBeDefined(); // fail

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();

Asserts that a number is even.

expect(2).toBeEven();
expect(1).not.toBeEven();

Asserts that a value is false.

expect(false).toBeFalse();
expect(true).not.toBeFalse();
expect(0).not.toBeFalse();

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();

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();

Asserts that a value is a function.

expect(() => {}).toBeFunction();

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

the expected number

expect(1).toBeGreaterThan(0);
expect(3.14).toBeGreaterThan(3);
expect(9).toBeGreaterThan(9); // fail

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

the expected number

expect(1).toBeGreaterThanOrEqual(0);
expect(3.14).toBeGreaterThanOrEqual(3);
expect(9).toBeGreaterThanOrEqual(9);

Asserts that the expected value is an instance of value

expect([]).toBeInstanceOf(Array);
expect(null).toBeInstanceOf(Array); // fail

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

expect(1).toBeInteger();
expect(3.14).not.toBeInteger();
expect(NaN).not.toBeInteger();

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

the expected number

expect(-1).toBeLessThan(0);
expect(3).toBeLessThan(3.14);
expect(9).toBeLessThan(9); // fail

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

the expected number

expect(-1).toBeLessThanOrEqual(0);
expect(3).toBeLessThanOrEqual(3.14);
expect(9).toBeLessThanOrEqual(9);

Asserts that a value is NaN.

Same as using Number.isNaN().

expect(NaN).toBeNaN();
expect(Infinity).toBeNaN(); // fail
expect("notanumber").toBeNaN(); // fail

Asserts that a value is a negative number.

expect(-3.14).toBeNegative();
expect(1).not.toBeNegative();
expect(NaN).not.toBeNegative();

Asserts that a value is null or undefined.

expect(null).toBeNil();
expect(undefined).toBeNil();

Asserts that a value is null.

expect(null).toBeNull();
expect(undefined).toBeNull(); // fail

Asserts that a value is a number.

expect(1).toBeNumber();
expect(3.14).toBeNumber();
expect(NaN).toBeNumber();
expect(BigInt(1)).not.toBeNumber();

Asserts that a value is an object.

expect({}).toBeObject();
expect("notAnObject").not.toBeObject();
expect(NaN).not.toBeObject();

Asserts that a number is odd.

expect(1).toBeOdd();
expect(2).not.toBeOdd();

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.

the expected value

expect(1).toBeOneOf([1,2,3]);
expect("foo").toBeOneOf(["foo", "bar"]);
expect(true).toBeOneOf(new Set([true]));

Asserts that a value is a positive number.

expect(1).toBePositive();
expect(-3.14).not.toBePositive();
expect(NaN).not.toBePositive();

Asserts that a value is a string.

expect("foo").toBeString();
expect(new String("bar")).toBeString();
expect(123).not.toBeString();

Asserts that a value is a symbol.

expect(Symbol("foo")).toBeSymbol();
expect("foo").not.toBeSymbol();

Asserts that a value is true.

expect(true).toBeTrue();
expect(false).not.toBeTrue();
expect(1).not.toBeTrue();

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();

Asserts that a value matches a specific type.

expect(1).toBeTypeOf("number");
expect("hello").toBeTypeOf("string");
expect([]).not.toBeTypeOf("boolean");

Asserts that a value is undefined.

expect(undefined).toBeUndefined();
expect(null).toBeUndefined(); // fail

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();

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

the start number (inclusive)

the end number (exclusive)

Asserts that a value contains what is expected.

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

the expected value

expect([1, 2, 3]).toContain(1);
expect(new Set([true])).toContain(true);
expect("hello").toContain("o");

Asserts that an object contains all the provided keys.

The value must be an object

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']);

Asserts that an object contain all the provided values.

The value must be an object

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']);

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

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']);

Asserts that an object contain any provided value.

The value must be an object

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']);

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.

the expected value

expect([{ a: 1 }]).toContainEqual({ a: 1 });
expect([{ a: 1 }]).not.toContainEqual({ a: 2 });

Asserts that an object contains a key.

The value must be an object

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');

Asserts that an object contains all the provided keys.

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']);

Asserts that an object contain the provided value.

This method is deep and will look through child properties to find the expected value.

The input value must be an object.

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" }]);

Asserts that an object contain the provided value.

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

The value must be an object

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']);

Asserts that a value ends with a string.

the string to end with

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

the expected value

expect(100 + 23).toBe(123);
expect("d" + "og").toBe("dog");
expect([456]).toEqual([456]);
expect({ value: 1 }).toEqual({ value: 1 });

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

the expected string

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

Ensures that a mock function is called.

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

Ensure that a mock function is called with specific arguments.

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

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

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.

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

the expected length

expect([]).toHaveLength(0);
expect("hello").toHaveLength(4);

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.

The 1-based index of the function call

The expected return value

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

the expected property name or path, or an index

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.

A promise that is unfulfilled will be considered a failure. If the function threw an error, it will be considered a failure.

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.

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

Asserts that a value includes a string.

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

the expected substring

Asserts that a value includes a string {times} times.

the expected substring

the number of times the substring should occur

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

the expected substring or pattern.

expect("dog").toMatch(/dog/);
expect("dog").toMatch("og");

Asserts that a value matches the most recent inline snapshot.

The latest automatically-updated snapshot value.

expect("Hello").toMatchInlineSnapshot();
expect("Hello").toMatchInlineSnapshot(`"Hello"`);

Asserts that a value matches the most recent inline snapshot.

Object containing properties to match against the 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,
}
`);

Asserts that an object matches a subset of properties.

Subset of properties to match with.

expect({ a: 1, b: 2 }).toMatchObject({ b: 2 });
expect({ c: new Date(), d: 2 }).toMatchObject({ d: 2 });

Asserts that a value matches the most recent snapshot.

Hint used to identify the snapshot in the snapshot file.

expect([1, 2, 3]).toMatchSnapshot('hint message');

Asserts that a value matches the most recent snapshot.

Object containing properties to match against the value.

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) });

Checks whether a value satisfies a custom condition.

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");

Asserts that a value starts with a string.

the string to start with

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

There are two key differences from toEqual():

the expected value

class Dog {
type = "dog";
}
const actual = new Dog();
expect(actual).toStrictEqual(new Dog());
expect(actual).toStrictEqual({ type: "dog" }); // fail

Asserts that a function throws an error.

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();

Asserts that a function throws an error.

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();

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

The latest automatically-updated snapshot value.

function fail() {
throw new Error("Oops!");
}
expect(fail).toThrowErrorMatchingInlineSnapshot();
expect(fail).toThrowErrorMatchingInlineSnapshot(`"Oops!"`);

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!");

Runs a test.

test("can check if using Bun", () => {
expect(Bun).toBeDefined();
});

test("can make a fetch() request", async () => {
const response = await fetch("https://example.com/");
expect(response.ok).toBe(true);
});

test("can set a timeout", async () => {
await Bun.sleep(100);
}, 50); // or { timeout: 50 }

Runs the test concurrently with other concurrent tests.

Marks this test as failing.

Use test.failing when you are writing a test and expecting it to fail. These tests will behave the other way normal tests do. If failing test will throw any errors then it will pass. If it does not throw it will fail.

test.failing is very similar to test.todo except that it always runs, regardless of the --todo flag.

Skips all other tests, except this test.

Forces the test to run serially (not in parallel), even when the --concurrent flag is used.

Skips this test.

Marks this test as to be written or to be fixed.

These tests will not be executed unless the --todo flag is passed. With the flag, if the test passes, the test will be marked as fail in the results; you will have to remove the .todo or check that your test is implemented correctly.

Runs the test concurrently with other concurrent tests, if condition is true.

if the test should run concurrently

Marks this test as failing, if condition is true.

if the test should be marked as failing

Runs this test, if condition is true.

This is the opposite of test.skipIf().

if the test should run

Forces the test to run serially (not in parallel), if condition is true. This applies even when the --concurrent flag is used.

if the test should run serially

Skips this test, if condition is true.

if the test should be skipped

Marks this test as to be written or to be fixed, if condition is true.

if the test should be marked TODO

Sets the number of times to repeat the test, regardless of whether it passed or failed.

Sets the number of times to retry the test if it fails.

Sets the timeout for the test in milliseconds.

If the test does not complete within this time, the test will fail with:

'Timeout: test {name} timed out after 5000ms'

Object representing an asymmetric matcher obtained by an static call to expect like expect.anything(), expect.stringContaining("..."), etc.

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

If the types has been defined through declaration merging, enforce it. Otherwise enforce the generic custom matcher signature.

Custom equality tester