Describes a group of related tests.
module
bun:test
The 'bun:test'
module is a fast, built-in test runner that aims for Jest compatibility. Tests are executed with the Bun runtime, providing significantly improved performance over traditional test runners.
Key features include TypeScript and JSX support, lifecycle hooks (beforeAll
, beforeEach
, afterEach
, afterAll
), snapshot testing, UI & DOM testing, watch mode, and script pre-loading. The API supports test assertions with expect
, test grouping with describe
, mocks, and more.
While Bun aims for compatibility with Jest, not everything is implemented yet. Use bun test
to automatically discover and run tests matching common patterns like *.test.ts
or *.spec.js
.
- fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void): void;
Runs a function, once, after all the tests.
This is useful for running clean up tasks, like closing a socket or deleting temporary files.
@param fnthe function to run
let database; afterAll(async () => { if (database) { await database.close(); } });
- fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void): void;
Runs a function after each test.
This is useful for running clean up tasks, like closing a socket or deleting temporary files.
@param fnthe function to run
- fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void): void;
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.
@param fnthe function to run
let database; beforeAll(async () => { database = await connect("localhost"); });
- fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void): void;
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.
@param fnthe function to run
- milliseconds: number): void;
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).
@param millisecondsthe number of milliseconds for the default timeout
- now?: number | Date): ThisType<void>;
Control the system time used by:
Date.now()
new Date()
Intl.DateTimeFormat().format()
In the future, we may add support for more functions, but we haven't done that yet.
@param nowThe time to set the system time to. If not provided, the system time will be reset.
@returnsthis
Type definitions
namespace jest
- type Mock<T extends (...args: any[]) => any = (...args: any[]) => any> = JestMock.Mock<T>
Constructs the type of a mock function, e.g. the return type of
jest.fn()
. - type Replaced<T> = JestMock.Replaced<T>
Constructs the type of a replaced property.
- type Spied<T extends JestMock.ClassLike | (...args: any[]) => any> = JestMock.Spied<T>
Constructs the type of a spied class or function.
- type SpiedClass<T extends JestMock.ClassLike> = JestMock.SpiedClass<T>
Constructs the type of a spied class.
- type SpiedFunction<T extends (...args: any[]) => any> = JestMock.SpiedFunction<T>
Constructs the type of a spied function.
- type SpiedGetter<T> = JestMock.SpiedGetter<T>
Constructs the type of a spied getter.
- type SpiedSetter<T> = JestMock.SpiedSetter<T>
Constructs the type of a spied setter.
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
ortoBeCalledWith
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
ortoBeCalledWith
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()); });
- arr: readonly E[]): any;
Matches any array made up entirely of elements in the provided array. You can use it inside
toEqual
ortoBeCalledWith
instead of a literal value.Optionally, you can provide a type for the elements via a generic.
- num: number,numDigits?: number): any;
Useful when comparing floating point numbers in object properties or array item. If you need to compare a number, use
.toBeCloseTo
instead.The optional
numDigits
argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion isMath.abs(expected - received) < 0.005
(that is,10 ** -2 / 2
). - obj: object): any;
Matches any object that recursively matches the provided keys. This is often handy in conjunction with other asymmetric matchers.
Optionally, you can provide a type for the object via a generic. This ensures that the object contains the desired structure.
- str: string | String): any;
Matches any received string that contains the exact expected string
- regex: string | String | RegExp): any;
Matches any string that contains the exact provided string
interface AsymmetricMatchersBuiltin
- 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
ortoBeCalledWith
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
ortoBeCalledWith
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()); });
- arr: readonly E[]): any;
Matches any array made up entirely of elements in the provided array. You can use it inside
toEqual
ortoBeCalledWith
instead of a literal value.Optionally, you can provide a type for the elements via a generic.
- num: number,numDigits?: number): any;
Useful when comparing floating point numbers in object properties or array item. If you need to compare a number, use
.toBeCloseTo
instead.The optional
numDigits
argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion isMath.abs(expected - received) < 0.005
(that is,10 ** -2 / 2
). - obj: object): any;
Matches any object that recursively matches the provided keys. This is often handy in conjunction with other asymmetric matchers.
Optionally, you can provide a type for the object via a generic. This ensures that the object contains the desired structure.
- str: string | String): any;
Matches any received string that contains the exact expected string
- regex: string | String | RegExp): any;
Matches any string that contains the exact provided string
interface Describe
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); }); });
- table: readonly T[]): (label: DescribeLabel, fn: (...args: [...T[]]) => void | Promise<unknown>, options?: number | TestOptions) => void;
Returns a function that runs for each item in
table
.@param tableArray of Arrays with the arguments that are passed into the test fn for each row.
table: readonly T[]): (label: DescribeLabel, fn: (...args: Readonly<T>) => void | Promise<unknown>, options?: number | TestOptions) => void;table: T[]): (label: DescribeLabel, fn: (...args: T[]) => void | Promise<unknown>, options?: number | TestOptions) => void; - if(condition: boolean): (label: DescribeLabel, fn: () => void) => void;
Runs this group of tests, only if
condition
is true.This is the opposite of
describe.skipIf()
.@param conditionif these tests should run
- @param label
the label for the tests
@param fnthe function that defines the tests
- @param label
the label for the tests
@param fnthe function that defines the tests
- condition: boolean): (label: DescribeLabel, fn: () => void) => void;
Skips this group of tests, if
condition
is true.@param conditionif these tests should be skipped
- todo(label: DescribeLabel,fn?: () => void): void;
Marks this group of tests as to be written or to be fixed.
@param labelthe label for the tests
@param fnthe function that defines the tests
- condition: boolean): (label: DescribeLabel, fn: () => void) => void;
Marks this group of tests as to be written or to be fixed, if
condition
is true.@param conditionif these tests should be skipped
interface Expect
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 {} }
- not: ExpectNot
Access to negated asymmetric matchers.
expect("abc").toEqual(expect.stringContaining("abc")); // will pass expect("abc").toEqual(expect.not.stringContaining("abc")); // will fail
- rejectsTo: AsymmetricMatchers
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
- resolvesTo: AsymmetricMatchers
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
- 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
ortoBeCalledWith
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
ortoBeCalledWith
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()); });
- arr: readonly E[]): any;
Matches any array made up entirely of elements in the provided array. You can use it inside
toEqual
ortoBeCalledWith
instead of a literal value.Optionally, you can provide a type for the elements via a generic.
- num: number,numDigits?: number): any;
Useful when comparing floating point numbers in object properties or array item. If you need to compare a number, use
.toBeCloseTo
instead.The optional
numDigits
argument limits the number of digits to check after the decimal point. For the default value 2, the test criterion isMath.abs(expected - received) < 0.005
(that is,10 ** -2 / 2
). - @param 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
- obj: object): any;
Matches any object that recursively matches the provided keys. This is often handy in conjunction with other asymmetric matchers.
Optionally, you can provide a type for the object via a generic. This ensures that the object contains the desired structure.
- str: string | String): any;
Matches any received string that contains the exact expected string
- regex: string | String | RegExp): any;
Matches any string that contains the exact provided string
- @param msg
Optional message to display if the test fails
@returnsnever
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"); } });
interface MatcherResult
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");
- pass: (message?: string) => void
Assertion which passes.
expect().pass(); expect().pass("message is optional"); expect().not.pass(); expect().not.pass("hi");
- ...expected: unknown[]): void;
Ensure that a mock function is called with specific arguments for the nth call.
- 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 expectedthe 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()
- For non-primitive values, like objects and arrays, use
Asserts that a value is a
array
.expect([1]).toBeArray(); expect(new Array(1)).toBeArray(); expect({}).not.toBeArray();
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.
- expected: number): void;
Ensure that a mock function is called with specific arguments.
- ...expected: unknown[]): void;
Ensure that a mock function is called with specific arguments.
- 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 expectedthe expected value
@param numDigitsthe 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
, usetoBe(false)
instead.expect(true).toBeTruthy(); expect(1).toBeTruthy(); expect({}).toBeTruthy();
Asserts that a value is a
number
, and is notNaN
orInfinity
.expect(1).toBeFinite(); expect(3.14).toBeFinite(); expect(NaN).not.toBeFinite(); expect(Infinity).not.toBeFinite();
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 expectedthe 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 expectedthe expected number
expect(1).toBeGreaterThanOrEqual(0); expect(3.14).toBeGreaterThanOrEqual(3); expect(9).toBeGreaterThanOrEqual(9);
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();
- expected: number | bigint): void;
Asserts that a value is a
number
and is less than the expected value.@param expectedthe 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 expectedthe 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
orundefined
.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();
- 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 expectedthe 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
, usetoBe(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");
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();
- start: number,end: number): void;
Asserts that a value is a number between a start and end value.
@param startthe start number (inclusive)
@param endthe end number (exclusive)
- expected: unknown): void;
Asserts that a value contains what is expected.
The value must be an array or iterable, which includes strings.
@param expectedthe expected value
expect([1, 2, 3]).toContain(1); expect(new Set([true])).toContain(true); expect("hello").toContain("o");
- expected: unknown): void;
Asserts that an
object
contains all the provided keys.The value must be an object
@param expectedthe 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: unknown): void;
Asserts that an
object
contain all the provided values.The value must be an object
@param expectedthe 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: unknown): void;
Asserts that an
object
contains at least one of the provided keys. Asserts that anobject
contains all the provided keys.The value must be an object
@param expectedthe 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: unknown): void;
Asserts that an
object
contain any provided value.The value must be an object
@param expectedthe 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: 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 expectedthe expected value
expect([{ a: 1 }]).toContainEqual({ a: 1 }); expect([{ a: 1 }]).not.toContainEqual({ a: 2 });
- expected: unknown): void;
Asserts that an
object
contains a key.The value must be an object
@param expectedthe 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');
- @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: unknown): void;
Asserts that an
object
contain the provided value.The value must be an object
@param expectedthe 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
contain the provided value.The value must be an object
@param expectedthe 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']);
- @param expected
the string to end with
- @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 });
- expected: string): void;
Asserts that a value is equal to the expected string, ignoring any whitespace.
@param expectedthe 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.
- length: number): void;
Asserts that a value has a
.length
property that is equal to the expected length.@param lengththe expected length
expect([]).toHaveLength(0); expect("hello").toHaveLength(4);
- keyPath: string | number | string | number[],value?: unknown): void;
Asserts that a value has a property with the expected name, and value if provided.
@param keyPaththe expected property name or path, or an index
@param valuethe 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.
- 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.
- expected: string): void;
Asserts that a value includes a
string
.For non-string values, use
toContain()
instead.@param expectedthe expected substring
- expected: string,times: number): void;
Asserts that a value includes a
string
{times} times.@param expectedthe expected substring
@param timesthe number of times the substring should occur
- expected: string | RegExp): void;
Asserts that a value matches a regular expression or includes a substring.
@param expectedthe 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 valueThe 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 propertyMatchersObject containing properties to match against the value.
@param valueThe 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>, } `);
- @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 });
- @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 propertyMatchersObject containing properties to match against the value.
@param hintHint 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;
Checks whether a value satisfies a custom condition.
@param predicateThe 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");
- @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()
:- It checks that the class is the same.
- It checks that
undefined
values match as well.
@param expectedthe expected value
class Dog { type = "dog"; } const actual = new Dog(); expect(actual).toStrictEqual(new Dog()); expect(actual).toStrictEqual({ type: "dog" }); // fail
- expected?: unknown): void;
Asserts that a function throws an error.
- If expected is a
string
orRegExp
, it will check themessage
property. - If expected is an
Error
object, it will check thename
andmessage
properties. - If expected is an
Error
constructor, it will check the class of theError
. - If expected is not provided, it will check if anything has thrown.
@param expectedthe 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();
- If expected is a
- expected?: unknown): void;
Asserts that a function throws an error.
- If expected is a
string
orRegExp
, it will check themessage
property. - If expected is an
Error
object, it will check thename
andmessage
properties. - If expected is an
Error
constructor, it will check the class of theError
. - If expected is not provided, it will check if anything has thrown.
@param expectedthe 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();
- If expected is a
- value?: string): void;
Asserts that a function throws an error matching the most recent snapshot.
@param valueThe 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.
function fail() { throw new Error("Oops!"); } expect(fail).toThrowErrorMatchingSnapshot(); expect(fail).toThrowErrorMatchingSnapshot("This one should say Oops!");
interface MatchersBuiltin<T = unknown>
- fail: (message?: string) => void
Assertion which fails.
expect().fail(); expect().fail("message is optional"); expect().not.fail(); expect().not.fail("hi");
- pass: (message?: string) => void
Assertion which passes.
expect().pass(); expect().pass("message is optional"); expect().not.pass(); expect().not.pass("hi");
- ...expected: unknown[]): void;
Ensure that a mock function is called with specific arguments for the nth call.
- 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 expectedthe 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()
- For non-primitive values, like objects and arrays, use
Asserts that a value is a
array
.expect([1]).toBeArray(); expect(new Array(1)).toBeArray(); expect({}).not.toBeArray();
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.
- expected: number): void;
Ensure that a mock function is called with specific arguments.
- ...expected: unknown[]): void;
Ensure that a mock function is called with specific arguments.
- 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 expectedthe expected value
@param numDigitsthe 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
, usetoBe(false)
instead.expect(true).toBeTruthy(); expect(1).toBeTruthy(); expect({}).toBeTruthy();
Asserts that a value is a
number
, and is notNaN
orInfinity
.expect(1).toBeFinite(); expect(3.14).toBeFinite(); expect(NaN).not.toBeFinite(); expect(Infinity).not.toBeFinite();
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 expectedthe 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 expectedthe expected number
expect(1).toBeGreaterThanOrEqual(0); expect(3.14).toBeGreaterThanOrEqual(3); expect(9).toBeGreaterThanOrEqual(9);
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();
- expected: number | bigint): void;
Asserts that a value is a
number
and is less than the expected value.@param expectedthe 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 expectedthe 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
orundefined
.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();
- 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 expectedthe 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
, usetoBe(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");
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();
- start: number,end: number): void;
Asserts that a value is a number between a start and end value.
@param startthe start number (inclusive)
@param endthe end number (exclusive)
- expected: unknown): void;
Asserts that a value contains what is expected.
The value must be an array or iterable, which includes strings.
@param expectedthe expected value
expect([1, 2, 3]).toContain(1); expect(new Set([true])).toContain(true); expect("hello").toContain("o");
- expected: unknown): void;
Asserts that an
object
contains all the provided keys.The value must be an object
@param expectedthe 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: unknown): void;
Asserts that an
object
contain all the provided values.The value must be an object
@param expectedthe 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: unknown): void;
Asserts that an
object
contains at least one of the provided keys. Asserts that anobject
contains all the provided keys.The value must be an object
@param expectedthe 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: unknown): void;
Asserts that an
object
contain any provided value.The value must be an object
@param expectedthe 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: 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 expectedthe expected value
expect([{ a: 1 }]).toContainEqual({ a: 1 }); expect([{ a: 1 }]).not.toContainEqual({ a: 2 });
- expected: unknown): void;
Asserts that an
object
contains a key.The value must be an object
@param expectedthe 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');
- @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: unknown): void;
Asserts that an
object
contain the provided value.The value must be an object
@param expectedthe 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
contain the provided value.The value must be an object
@param expectedthe 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']);
- @param expected
the string to end with
- @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 });
- expected: string): void;
Asserts that a value is equal to the expected string, ignoring any whitespace.
@param expectedthe 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.
- length: number): void;
Asserts that a value has a
.length
property that is equal to the expected length.@param lengththe expected length
expect([]).toHaveLength(0); expect("hello").toHaveLength(4);
- keyPath: string | number | string | number[],value?: unknown): void;
Asserts that a value has a property with the expected name, and value if provided.
@param keyPaththe expected property name or path, or an index
@param valuethe 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.
- 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.
- expected: string): void;
Asserts that a value includes a
string
.For non-string values, use
toContain()
instead.@param expectedthe expected substring
- expected: string,times: number): void;
Asserts that a value includes a
string
{times} times.@param expectedthe expected substring
@param timesthe number of times the substring should occur
- expected: string | RegExp): void;
Asserts that a value matches a regular expression or includes a substring.
@param expectedthe 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 valueThe 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 propertyMatchersObject containing properties to match against the value.
@param valueThe 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>, } `);
- @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 });
- @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 propertyMatchersObject containing properties to match against the value.
@param hintHint 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;
Checks whether a value satisfies a custom condition.
@param predicateThe 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");
- @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()
:- It checks that the class is the same.
- It checks that
undefined
values match as well.
@param expectedthe expected value
class Dog { type = "dog"; } const actual = new Dog(); expect(actual).toStrictEqual(new Dog()); expect(actual).toStrictEqual({ type: "dog" }); // fail
- expected?: unknown): void;
Asserts that a function throws an error.
- If expected is a
string
orRegExp
, it will check themessage
property. - If expected is an
Error
object, it will check thename
andmessage
properties. - If expected is an
Error
constructor, it will check the class of theError
. - If expected is not provided, it will check if anything has thrown.
@param expectedthe 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();
- If expected is a
- expected?: unknown): void;
Asserts that a function throws an error.
- If expected is a
string
orRegExp
, it will check themessage
property. - If expected is an
Error
object, it will check thename
andmessage
properties. - If expected is an
Error
constructor, it will check the class of theError
. - If expected is not provided, it will check if anything has thrown.
@param expectedthe 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();
- If expected is a
- value?: string): void;
Asserts that a function throws an error matching the most recent snapshot.
@param valueThe 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.
function fail() { throw new Error("Oops!"); } expect(fail).toThrowErrorMatchingSnapshot(); expect(fail).toThrowErrorMatchingSnapshot("This one should say Oops!");
interface Test
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 }
- table: readonly T[]): (label: string, fn: (...args: [...T[]]) => void | Promise<unknown>, options?: number | TestOptions) => void;
Returns a function that runs for each item in
table
.@param tableArray of Arrays with the arguments that are passed into the test fn for each row.
table: readonly T[]): (label: string, fn: (...args: Readonly<T>) => void | Promise<unknown>, options?: number | TestOptions) => void;table: T[]): (label: string, fn: (...args: T[]) => void | Promise<unknown>, options?: number | TestOptions) => void; - label: string,fn?: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void,): void;
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.@param labelthe label for the test
@param fnthe test function
@param optionsthe test timeout or options
- if(condition: boolean): (label: string, fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void, options?: number | TestOptions) => void;
Runs this test, if
condition
is true.This is the opposite of
test.skipIf()
.@param conditionif the test should run
- only(label: string,fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void,): void;
Skips all other tests, except this test when run with the
--only
option.@param labelthe label for the test
@param fnthe test function
@param optionsthe test timeout or options
- skip(label: string,fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void,): void;
Skips this test.
@param labelthe label for the test
@param fnthe test function
@param optionsthe test timeout or options
- condition: boolean): (label: string, fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void, options?: number | TestOptions) => void;
Skips this test, if
condition
is true.@param conditionif the test should be skipped
- todo(label: string,fn?: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void,): void;
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 asfail
in the results; you will have to remove the.todo
or check that your test is implemented correctly.@param labelthe label for the test
@param fnthe test function
@param optionsthe test timeout or options
- condition: boolean): (label: string, fn: () => void | Promise<unknown> | (done: (err?: unknown) => void) => void, options?: number | TestOptions) => void;
Marks this test as to be written or to be fixed, if
condition
is true.@param conditionif the test should be marked TODO
interface TesterContext
interface TestOptions
- type AsymmetricMatcher = any
Object representing an asymmetric matcher obtained by an static call to expect like
expect.anything()
,expect.stringContaining("...")
, etc. - type CustomMatcher<E, P extends any[]> = (this: MatcherContext, expected: E, ...matcherArguments: P) => MatcherResult | Promise<MatcherResult>
- 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
- type EqualsFunction = (a: unknown, b: unknown) => boolean
- type ExpectExtendMatchers<M> = { [K in keyof M]: k extends keyof CustomMatchersDetected ? CustomMatcher<unknown, Parameters<CustomMatchersDetected[k]>> : CustomMatcher<unknown, any[]> }
If the types has been defined through declaration merging, enforce it. Otherwise enforce the generic custom matcher signature.
- type Mock<T extends (...args: any[]) => any> = JestMock.Mock<T>
-- Mocks --
- type Tester = (this: TesterContext, a: any, b: any, customTesters: Tester[]) => boolean | undefined
Custom equality tester