Interface Expected<IsAsync>

The Expected interface defines the available assertion methods.

interface Expected<IsAsync> {
    not: IsAsync extends true
        ? Async<Expected<true>>
        : Expected<false>;
    rejects: Async<Expected<true>>;
    resolves: Async<Expected<true>>;
    toEqualBook: ((expected: unknown) => ExtendMatchResult);
    lastCalledWith(...expected: unknown[]): void;
    lastReturnedWith(expected: unknown): void;
    nthCalledWith(nth: number, ...expected: unknown[]): void;
    nthReturnedWith(nth: number, expected: unknown): void;
    toBe(expected: unknown): void;
    toBeCalled(): void;
    toBeCalledTimes(expected: number): void;
    toBeCalledWith(...expected: unknown[]): void;
    toBeCloseTo(candidate: number, tolerance?: number): void;
    toBeDefined(): void;
    toBeFalsy(): void;
    toBeGreaterThan(expected: number): void;
    toBeGreaterThanOrEqual(expected: number): void;
    toBeInstanceOf<T>(expected: T): void;
    toBeLessThan(expected: number): void;
    toBeLessThanOrEqual(expected: number): void;
    toBeNaN(): void;
    toBeNull(): void;
    toBeTruthy(): void;
    toBeUndefined(): void;
    toContain(expected: unknown): void;
    toContainEqual(expected: unknown): void;
    toEqual(expected: unknown): void;
    toHaveBeenCalled(): void;
    toHaveBeenCalledTimes(expected: number): void;
    toHaveBeenCalledWith(...expected: unknown[]): void;
    toHaveBeenLastCalledWith(...expected: unknown[]): void;
    toHaveBeenNthCalledWith(nth: number, ...expected: unknown[]): void;
    toHaveLastReturnedWith(expected: unknown): void;
    toHaveLength(expected: number): void;
    toHaveNthReturnedWith(nth: number, expected: unknown): void;
    toHaveProperty(propName: string | string[], value?: unknown): void;
    toHaveReturned(): void;
    toHaveReturnedTimes(expected: number): void;
    toHaveReturnedWith(expected: unknown): void;
    toMatch(expected: RegExp): void;
    toMatchObject(expected: Record<PropertyKey, unknown> | Record<PropertyKey, unknown>[]): void;
    toReturn(): void;
    toReturnTimes(expected: number): void;
    toReturnWith(expected: unknown): void;
    toStrictEqual(candidate: unknown): void;
    toThrow<E>(expected?:
        | string
        | RegExp
        | E
        | (new (...args: any[]) => E)): void;
    [name: string]: unknown;
}

Type Parameters

IsAsync = false

Indexable

[name: string]: unknown
Additional custom assertion methods can be added here.

Properties

not

not: IsAsync extends true
? Async<Expected<true>>
: Expected<false>

The negation object that allows chaining negated assertions.

rejects

rejects: Async<Expected<true>>

The object that allows chaining assertions with async functions that are expected to throw an error.

resolves

resolves: Async<Expected<true>>

The object that allows chaining assertions with async functions that are expected to resolve to a value.

toEqualBook

toEqualBook: ((expected: unknown) => ExtendMatchResult)

Methods

lastCalledWith

lastCalledWith(...expected): void

Asserts that the function was called with the specified arguments.

Parameters

Rest...expected: unknown[]
The expected arguments.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock("foo", 42);
mock("bar", 43)

expect(mock).lastCalledWith("bar", 43);
expect(mock).not.lastCalledWith("foo", 42);

lastReturnedWith

lastReturnedWith(expected): void

Asserts that the function returned the specified value.

Parameters

expected: unknown

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn((str: string, num: number) => [str, num]);
mock("foo", 42);
mock("bar", 43);

expect(mock).lastReturnedWith(["bar", 43]);
expect(mock).not.lastReturnedWith(["foo", 42]);

@param expected The expected return value

nthCalledWith

nthCalledWith(nth, ...expected): void

Asserts that the function was called with the specified arguments at the specified call index.

Parameters

nth: number
The call index.
Rest...expected: unknown[]
The expected arguments.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock("foo", 42);
mock("bar", 43);
mock("baz", 44);

expect(mock).nthCalledWith(1, "foo", 42);
expect(mock).nthCalledWith(2, "bar", 43);
expect(mock).nthCalledWith(3, "baz", 44);

nthReturnedWith

nthReturnedWith(nth, expected): void

Asserts that the function returned the specified value at the specified call index.

Parameters

nth: number
The call index.
expected: unknown
The expected return value.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn((str: string, num: number) => [str, num]);
mock("foo", 42);
mock("bar", 43);
mock("baz", 44);

expect(mock).nthReturnedWith(1, ["foo", 42]);
expect(mock).nthReturnedWith(2, ["bar", 43]);
expect(mock).nthReturnedWith(3, ["baz", 44]);

toBe

toBe(expected): void

Asserts that the value is equal to the specified value.

Parameters

expected: unknown
The expected value.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(42).toBe(42);
expect("foo").toBe("foo");

const obj = {};
expect(obj).toBe(obj);
expect(obj).not.toBe({});

toBeCalled

toBeCalled(): void

Asserts that the function was called at least once.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
const mock2 = fn();
mock();

expect(mock).toBeCalled();
expect(mock2).not.toBeCalled();

toBeCalledTimes

toBeCalledTimes(expected): void

Asserts that the function was called the specified number of times.

Parameters

expected: number
The expected number of times.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock();
mock();

expect(mock).not.toBeCalledTimes(1);
expect(mock).toBeCalledTimes(2);
expect(mock).not.toBeCalledTimes(3);

toBeCalledWith

toBeCalledWith(...expected): void

Asserts that the function was called with the specified arguments.

Parameters

Rest...expected: unknown[]
The expected arguments.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock("foo", 42);
mock("bar", 43);

expect(mock).toBeCalledWith("foo", 42);
expect(mock).toBeCalledWith("bar", 43);
expect(mock).not.toBeCalledWith("baz", 44);

toBeCloseTo

toBeCloseTo(candidate, tolerance?): void
Asserts that a given numerical value is approximately equal to an expected number within a certain margin of error (tolerance). Useful when comparing floating-point numbers, which may be represented internally with precision errors.
Parameters
- candidate: number
  The candidate number.
- Optionaltolerance: number
  The number of significant decimal digits to consider when comparing the values (optional, default 2).
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(0.2 + 0.1).toBeCloseTo(0.3);
expect(0.2 + 0.1).toBeCloseTo(0.3, 15);
expect(0.2 + 0.1).not.toBeCloseTo(0.3, 16);
```
- Defined in expect/_types.ts:198

toBeDefined

toBeDefined(): void

Asserts that the value is defined.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(null).toBeDefined();
expect(undefined).not.toBeDefined();

toBeFalsy

toBeFalsy(): void

Asserts that the value is falsy.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(null).toBeFalsy();
expect(undefined).toBeFalsy();
expect(0).toBeFalsy();
expect("").toBeFalsy();
expect(false).toBeFalsy();
expect(NaN).toBeFalsy();

expect(1).not.toBeFalsy();
expect("foo").not.toBeFalsy();
expect([]).not.toBeFalsy();

toBeGreaterThan

toBeGreaterThan(expected): void
Asserts that the value is greater than the specified number.
Parameters
- expected: number
  The expected number.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(2).toBeGreaterThan(1);
expect(2).not.toBeGreaterThan(2);
expect(2).not.toBeGreaterThan(3);
```
- Defined in expect/_types.ts:248

toBeGreaterThanOrEqual

toBeGreaterThanOrEqual(expected): void
Asserts that the value is greater than or equal to the specified number.
Parameters
- expected: number
  The expected number.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(2).toBeGreaterThanOrEqual(1);
expect(2).toBeGreaterThanOrEqual(2);
expect(2).not.toBeGreaterThanOrEqual(3);
```
- Defined in expect/_types.ts:264

toBeInstanceOf

toBeInstanceOf<T>(expected): void
Asserts that the value is an instance of the specified constructor.
Type Parameters
- T extends AnyConstructor
Parameters
- expected: T
  The expected constructor.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(new Error()).toBeInstanceOf(Error);
expect(new Error()).not.toBeInstanceOf(TypeError);
```
- Defined in expect/_types.ts:279

toBeLessThan

toBeLessThan(expected): void
Asserts that the value is less than the specified number.
Parameters
- expected: number
  The expected number.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(1).toBeLessThan(2);
expect(1).not.toBeLessThan(1);
expect(1).not.toBeLessThan(0);
```
- Defined in expect/_types.ts:295

toBeLessThanOrEqual

toBeLessThanOrEqual(expected): void
Asserts that the value is less than or equal to the specified number.
Parameters
- expected: number
  The expected number.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(1).toBeLessThanOrEqual(2);
expect(1).toBeLessThanOrEqual(1);
expect(1).not.toBeLessThanOrEqual(0);
```
- Defined in expect/_types.ts:311

toBeNaN

toBeNaN(): void

Asserts that the value is NaN.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(NaN).toBeNaN();
expect(1).not.toBeNaN();
expect(undefined).toBeNaN();
expect(null).not.toBeNaN();

toBeNull

toBeNull(): void

Asserts that the value is null.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(null).toBeNull();
expect(undefined).not.toBeNull();

toBeTruthy

toBeTruthy(): void

Asserts that the value is truthy.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(1).toBeTruthy();
expect("foo").toBeTruthy();
expect([]).toBeTruthy();
expect({}).toBeTruthy();
expect(true).toBeTruthy();

expect(0).not.toBeTruthy();
expect("").not.toBeTruthy();
expect(null).not.toBeTruthy();
expect(undefined).not.toBeTruthy();
expect(false).not.toBeTruthy();
expect(NaN).not.toBeTruthy();

toBeUndefined

toBeUndefined(): void

Asserts that the value is undefined.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(undefined).toBeUndefined();
expect(null).not.toBeUndefined();

toContain

toContain(expected): void

Asserts that the value contains the specified value (shallow equality).

Parameters

expected: unknown
The expected value.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect([1, 2, 3]).toContain(2);
expect([1, 2, 3]).not.toContain(4);

const item0 = { foo: 42 };
const item1 = { bar: 43 };
const items = [item0, item1];
expect(items).toContain(item1);
expect(items).not.toContain({ foo: 42 });

toContainEqual

toContainEqual(expected): void

Asserts that the value contains the specified value (deep equality).

Parameters

expected: unknown
The expected value.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect([1, 2, 3]).toContainEqual(2);
expect([1, 2, 3]).not.toContainEqual(4);

expect([{ foo: 42 }, { bar: 43 }]).toContainEqual({ bar: 43 });
expect([{ foo: 42 }, { bar: 43 }]).not.toContainEqual({ baz: 44 });

toEqual

toEqual(expected): void
Asserts that the value is equal to the specified value (deep equality).
Parameters
- expected: unknown
  The expected value.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect(42).toEqual(42);
expect({ foo: 42 }).toEqual({ foo: 42 });
expect([1, 2, 3]).toEqual([1, 2, 3]);
```
- Defined in expect/_types.ts:448

toHaveBeenCalled

toHaveBeenCalled(): void

Asserts that the function was called at least once.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
const mock2 = fn();

mock();

expect(mock).toHaveBeenCalled();
expect(mock2).not.toHaveBeenCalled();

toHaveBeenCalledTimes

toHaveBeenCalledTimes(expected): void

Asserts that the function was called the specified number of times.

Parameters

expected: number
The expected number of times.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock();
mock();

expect(mock).not.toHaveBeenCalledTimes(1);
expect(mock).toHaveBeenCalledTimes(2);
expect(mock).not.toHaveBeenCalledTimes(3);

toHaveBeenCalledWith

toHaveBeenCalledWith(...expected): void

Asserts that the function was called with the specified arguments.

Parameters

Rest...expected: unknown[]
The expected arguments.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock("foo", 42);
mock("bar", 43);

expect(mock).toHaveBeenCalledWith("foo", 42);
expect(mock).toHaveBeenCalledWith("bar", 43);
expect(mock).not.toHaveBeenCalledWith("baz", 44);

toHaveBeenLastCalledWith

toHaveBeenLastCalledWith(...expected): void

Asserts that the function was last called with the specified arguments.

Parameters

Rest...expected: unknown[]
The expected arguments.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock("foo", 42);
mock("bar", 43);

expect(mock).toHaveBeenLastCalledWith("bar", 43);
expect(mock).not.toHaveBeenLastCalledWith("foo", 42);

toHaveBeenNthCalledWith

toHaveBeenNthCalledWith(nth, ...expected): void

Asserts that the function was called with the specified arguments at the specified call index.

Parameters

nth: number
The call index.
Rest...expected: unknown[]
The expected arguments.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock("foo", 42);
mock("bar", 43);
mock("baz", 44);

expect(mock).toHaveBeenNthCalledWith(1, "foo", 42);
expect(mock).toHaveBeenNthCalledWith(2, "bar", 43);
expect(mock).toHaveBeenNthCalledWith(3, "baz", 44);

toHaveLastReturnedWith

toHaveLastReturnedWith(expected): void

Asserts that the function last returned the specified value.

Parameters

expected: unknown
The expected return value.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn((str: string, num: number) => [str, num]);
mock("foo", 42);
mock("bar", 43);

expect(mock).toHaveLastReturnedWith(["bar", 43]);
expect(mock).not.toHaveLastReturnedWith(["foo", 42]);

toHaveLength

toHaveLength(expected): void
Asserts that the value has the specified length.
Parameters
- expected: number
  The expected length.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect([1, 2, 3]).toHaveLength(3);
expect("foo").toHaveLength(3);
expect([]).toHaveLength(0);
```
- Defined in expect/_types.ts:561

toHaveNthReturnedWith

toHaveNthReturnedWith(nth, expected): void

Asserts that the function returned the specified value at the specified call index.

Parameters

nth: number
The call index.
expected: unknown
The expected return value.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn((str: string, num: number) => [str, num]);
mock("foo", 42);
mock("bar", 43);
mock("baz", 44);

expect(mock).toHaveNthReturnedWith(1, ["foo", 42]);
expect(mock).toHaveNthReturnedWith(2, ["bar", 43]);
expect(mock).toHaveNthReturnedWith(3, ["baz", 44]);

toHaveProperty

toHaveProperty(propName, value?): void
Asserts that the value has the specified property with an optional value.
Parameters
- propName: string | string[]
  The property name or an array of property names.
- Optionalvalue: unknown
  The expected value (optional).
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect({ foo: 42 }).toHaveProperty("foo");
expect({ foo: 42 }).toHaveProperty("foo", 42);
expect({ foo: 42 }).not.toHaveProperty("bar");
```
- Defined in expect/_types.ts:619

toHaveReturned

toHaveReturned(): void

Asserts that the function returned.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();

expect(mock).not.toHaveReturned();

mock();

expect(mock).toHaveReturned();

toHaveReturnedTimes

toHaveReturnedTimes(expected): void
Asserts that the function returned the specified number of times.
Parameters
- expected: number
  The expected number of times.
Returns void
Example: Usage
```
import { expect, fn } from "@std/expect";

const mock = fn();
mock();
mock();

expect(mock).toHaveReturnedTimes(2);
expect(mock).not.toHaveReturnedTimes(3);
```
- Defined in expect/_types.ts:638

toHaveReturnedWith

toHaveReturnedWith(expected): void

Asserts that the function returned the specified value.

Parameters

expected: unknown
The expected return value.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mockFn = fn((x: number) => ({ foo: x + 1 }));

mockFn(5);
mockFn(6);

expect(mockFn).toHaveReturnedWith({ foo: 7 });
expect(mockFn).not.toHaveReturnedWith({ foo: 5 });

toMatch

toMatch(expected): void
Asserts that the value matches the specified regular expression.
Parameters
- expected: RegExp
  The expected regular expression.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect("foo").toMatch(/^foo$/);
expect("bar").not.toMatch(/^foo$/);
```
- Defined in expect/_types.ts:691

toMatchObject

toMatchObject(expected): void
Asserts that the value matches the specified object (deep equality).
Parameters
- expected: Record<PropertyKey, unknown> | Record<PropertyKey, unknown>[]
  The expected object or array of objects.
Returns void
Example: Usage
```
import { expect } from "@std/expect";

expect({ foo: 42 }).toMatchObject({ foo: 42 });
expect({ foo: 42 }).not.toMatchObject({ foo: 43 });
```
- Defined in expect/_types.ts:706

toReturn

toReturn(): void

Asserts that the function returned.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();

expect(mock).not.toReturn();

mock();

expect(mock).toReturn

toReturnTimes

toReturnTimes(expected): void

Asserts that the function returns the specified number of times.

Parameters

expected: number
The expected number of times.

Returns void

Example: Usage

import { expect, fn } from "@std/expect";

const mock = fn();
mock();
mock();

expect(mock).not.toReturnTimes(1);
expect(mock).toReturnTimes(2);
expect(mock).not.toReturnTimes(3);

toReturnWith

toReturnWith(expected): void
Asserts that the function returns the specified value.
Parameters
- expected: unknown
  The expected return value.
Returns void
Example: Usage
```
import { expect, fn } from "@std/expect";

const mock = fn(() => 42);

// expect(mock).toReturnWith(42);
expect(mock).not.toReturnWith(43);
```
- Defined in expect/_types.ts:763

toStrictEqual

toStrictEqual(candidate): void

Asserts that the value is strictly equal to the specified value.

Parameters

candidate: unknown
The candidate value.

Returns void

Example: Usage

import { expect } from "@std/expect";

expect(42).toStrictEqual(42);
expect("foo").toStrictEqual("foo");

const obj = {};
expect(obj).toStrictEqual(obj);

class LaCroix {
  flavor: string;

  constructor(flavor: string) {
    this.flavor = flavor;
  }
}
expect(new LaCroix("lemon")).not.toStrictEqual({ flavor: "lemon" });

toThrow

toThrow<E>(expected?): void

Asserts that the function throws an error.

Type Parameters

E extends Error = Error

Parameters

Optionalexpected:
    | string
    | RegExp
    | E
    | (new (...args: any[]) => E)
The expected error message, regular expression, or error constructor.

Returns void

Example: Usage

import { expect } from "@std/expect";

const fn = () => { throw new TypeError("foo") };
const fn2 = () => {};

expect(fn).toThrow();
expect(fn2).not.toThrow();

expect(fn).toThrow(TypeError);
expect(fn).toThrow("foo");
expect(fn).toThrow(/foo/);

expect(fn).not.toThrow(SyntaxError);
expect(fn).not.toThrow("bar");
expect(fn).not.toThrow(/bar/);