Expected

import { Expected } from "jsr:@ende/expect";

interface

interface Expected<IsAsync = false>

The Expected interface defines the available assertion methods.

Index signatures

`Index signature`

[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.

`resolves`

resolves: Async<Expected<true>>

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

`rejects`

rejects: Async<Expected<true>>

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

Methods

`lastCalledWith`

lastCalledWith(...expected: unknown[]): void

Asserts that the function was called with the specified arguments.

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

Example: Usage

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

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

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

`lastReturnedWith`

lastReturnedWith(expected: unknown): void

Asserts that the function returned the specified value.

Example: Usage

import { expect, fn } from "@ende/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: number, ...expected: unknown[]): void

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

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

Example: Usage

import { expect, fn } from "@ende/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: number, expected: unknown): void

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

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

Example: Usage

import { expect, fn } from "@ende/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]);

`toBeCalled`

toBeCalled(): void

Asserts that the function was called at least once.

Example: Usage

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

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

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

`toBeCalledTimes`

toBeCalledTimes(expected: number): void

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

expected: number: The expected number of times.

Example: Usage

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

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

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

`toBeCalledWith`

toBeCalledWith(...expected: unknown[]): void

Asserts that the function was called with the specified arguments.

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

Example: Usage

import { expect, fn } from "@ende/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: number, tolerance?: number): 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.

candidate: number: The candidate number.
tolerance?: number: The number of significant decimal digits to consider when comparing the values (optional, default 2).

Example: Usage

import { expect } from "@ende/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);

`toBeDefined`

toBeDefined(): void

Asserts that the value is defined.

Example: Usage

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

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

`toBeFalsy`

toBeFalsy(): void

Asserts that the value is falsy.

Example: Usage

import { expect } from "@ende/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: number): void

Asserts that the value is greater than the specified number.

expected: number: The expected number.

Example: Usage

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

expect(2).toBeGreaterThan(1);
expect(2).not.toBeGreaterThan(2);
expect(2).not.toBeGreaterThan(3);

`toBeGreaterThanOrEqual`

toBeGreaterThanOrEqual(expected: number): void

Asserts that the value is greater than or equal to the specified number.

expected: number: The expected number.

Example: Usage

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

expect(2).toBeGreaterThanOrEqual(1);
expect(2).toBeGreaterThanOrEqual(2);
expect(2).not.toBeGreaterThanOrEqual(3);

`toBeInstanceOf`

toBeInstanceOf<T extends AnyConstructor>(expected: T): void

Asserts that the value is an instance of the specified constructor.

expected: T: The expected constructor.

Example: Usage

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

expect(new Error()).toBeInstanceOf(Error);
expect(new Error()).not.toBeInstanceOf(TypeError);

`toBeLessThan`

toBeLessThan(expected: number): void

Asserts that the value is less than the specified number.

expected: number: The expected number.

Example: Usage

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

expect(1).toBeLessThan(2);
expect(1).not.toBeLessThan(1);
expect(1).not.toBeLessThan(0);

`toBeLessThanOrEqual`

toBeLessThanOrEqual(expected: number): void

Asserts that the value is less than or equal to the specified number.

expected: number: The expected number.

Example: Usage

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

expect(1).toBeLessThanOrEqual(2);
expect(1).toBeLessThanOrEqual(1);
expect(1).not.toBeLessThanOrEqual(0);

`toBeNaN`

toBeNaN(): void

Asserts that the value is NaN.

Example: Usage

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

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

`toBeNull`

toBeNull(): void

Asserts that the value is null.

Example: Usage

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

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

`toBeTruthy`

toBeTruthy(): void

Asserts that the value is truthy.

Example: Usage

import { expect } from "@ende/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.

Example: Usage

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

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

`toBe`

toBe(expected: unknown): void

Asserts that the value is equal to the specified value.

expected: unknown: The expected value.

Example: Usage

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

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

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

`toContainEqual`

toContainEqual(expected: unknown): void

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

expected: unknown: The expected value.

Example: Usage

import { expect } from "@ende/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 });

`toContain`

toContain(expected: unknown): void

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

expected: unknown: The expected value.

Example: Usage

import { expect } from "@ende/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 });

`toEqual`

toEqual(expected: unknown): void

Asserts that the value is equal to the specified value (deep equality).

expected: unknown: The expected value.

Example: Usage

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

expect(42).toEqual(42);
expect({ foo: 42 }).toEqual({ foo: 42 });
expect([1, 2, 3]).toEqual([1, 2, 3]);

`toHaveBeenCalledTimes`

toHaveBeenCalledTimes(expected: number): void

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

expected: number: The expected number of times.

Example: Usage

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

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

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

`toHaveBeenCalledWith`

toHaveBeenCalledWith(...expected: unknown[]): void

Asserts that the function was called with the specified arguments.

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

Example: Usage

import { expect, fn } from "@ende/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);

`toHaveBeenCalled`

toHaveBeenCalled(): void

Asserts that the function was called at least once.

Example: Usage

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

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

mock();

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

`toHaveBeenLastCalledWith`

toHaveBeenLastCalledWith(...expected: unknown[]): void

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

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

Example: Usage

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

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

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

`toHaveBeenNthCalledWith`

toHaveBeenNthCalledWith(nth: number, ...expected: unknown[]): void

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

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

Example: Usage

import { expect, fn } from "@ende/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);

`toHaveLength`

toHaveLength(expected: number): void

Asserts that the value has the specified length.

expected: number: The expected length.

Example: Usage

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

expect([1, 2, 3]).toHaveLength(3);
expect("foo").toHaveLength(3);
expect([]).toHaveLength(0);

`toHaveLastReturnedWith`

toHaveLastReturnedWith(expected: unknown): void

Asserts that the function last returned the specified value.

expected: unknown: The expected return value.

Example: Usage

import { expect, fn } from "@ende/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]);

`toHaveNthReturnedWith`

toHaveNthReturnedWith(nth: number, expected: unknown): void

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

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

Example: Usage

import { expect, fn } from "@ende/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: string | string[], value?: unknown): void

Asserts that the value has the specified property with an optional value.

propName: string | string[]: The property name or an array of property names.
value?: unknown: The expected value (optional).

Example: Usage

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

expect({ foo: 42 }).toHaveProperty("foo");
expect({ foo: 42 }).toHaveProperty("foo", 42);
expect({ foo: 42 }).not.toHaveProperty("bar");

`toHaveReturnedTimes`

toHaveReturnedTimes(expected: number): void

Asserts that the function returned the specified number of times.

expected: number: The expected number of times.

Example: Usage

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

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

expect(mock).toHaveReturnedTimes(2);
expect(mock).not.toHaveReturnedTimes(3);

`toHaveReturnedWith`

toHaveReturnedWith(expected: unknown): void

Asserts that the function returned the specified value.

expected: unknown: The expected return value.

Example: Usage

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

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

mockFn(5);
mockFn(6);

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

`toHaveReturned`

toHaveReturned(): void

Asserts that the function returned.

Example: Usage

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

const mock = fn();

expect(mock).not.toHaveReturned();

mock();

expect(mock).toHaveReturned();

`toMatch`

toMatch(expected: RegExp): void

Asserts that the value matches the specified regular expression.

expected: RegExp: The expected regular expression.

Example: Usage

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

expect("foo").toMatch(/^foo$/);
expect("bar").not.toMatch(/^foo$/);

`toMatchObject`

toMatchObject(expected: Record<PropertyKey, unknown> | Record<PropertyKey, unknown>[]): void

Asserts that the value matches the specified object (deep equality).

expected: Record<PropertyKey, unknown> | Record<PropertyKey, unknown>[]: The expected object or array of objects.

Example: Usage

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

expect({ foo: 42 }).toMatchObject({ foo: 42 });
expect({ foo: 42 }).not.toMatchObject({ foo: 43 });

`toMatchSnapshot`

toMatchSnapshot(hint?: string): void

Asserts that the value matches the most recent snapshot. If no snapshot exists, one will be created when running in update mode (-- --update).

Requires expect.setState({ currentTestName: "..." }) to be called before use. The test file path is auto-detected from the call stack.

hint?: string: An optional hint string appended to the snapshot name.

Example: Usage

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

Ende.test("snapshot test", () => {
  expect.setState({ currentTestName: "snapshot test", testPath: import.meta.url });
  expect({ foo: 42 }).toMatchSnapshot();
});

toMatchSnapshot(propertyMatchers: Record<string, unknown>, hint?: string): void

Asserts that the value matches the most recent snapshot, using property matchers to handle dynamic values like timestamps or IDs.

propertyMatchers: Record<string, unknown>: An object of asymmetric matchers for dynamic values.
hint?: string: An optional hint string appended to the snapshot name.

Example: Usage

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

Ende.test("snapshot with matchers", () => {
  expect.setState({ currentTestName: "snapshot with matchers", testPath: import.meta.url });
  expect({ id: 1, name: "Alice" }).toMatchSnapshot({
    id: expect.any(Number),
  });
});

`toMatchInlineSnapshot`

toMatchInlineSnapshot(inlineSnapshot?: string): void

Asserts that the value matches the inline snapshot string. If no snapshot is provided or the value differs, the source file will be updated when running in update mode (-- --update).

inlineSnapshot?: string: The expected inline snapshot string.

Example: Usage

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

Ende.test("inline snapshot", () => {
  expect({ foo: 42 }).toMatchInlineSnapshot(`
{
  foo: 42,
}
`);
});

toMatchInlineSnapshot(propertyMatchers: Record<string, unknown>, inlineSnapshot?: string): void

Asserts that the value matches the inline snapshot string, using property matchers to handle dynamic values like timestamps or IDs.

propertyMatchers: Record<string, unknown>: An object of asymmetric matchers for dynamic values.
inlineSnapshot?: string: The expected inline snapshot string.

Example: Usage

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

Ende.test("inline snapshot with matchers", () => {
  expect({ id: 1, name: "Alice" }).toMatchInlineSnapshot({
    id: expect.any(Number),
  }, `
{
  id: Any<Number>,
  name: "Alice",
}
`);
});

`toReturn`

toReturn(): void

Asserts that the function returned.

Example: Usage

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

const mock = fn();

expect(mock).not.toReturn();

mock();

expect(mock).toReturn();

`toReturnTimes`

toReturnTimes(expected: number): void

Asserts that the function returns the specified number of times.

expected: number: The expected number of times.

Example: Usage

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

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

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

`toReturnWith`

toReturnWith(expected: unknown): void

Asserts that the function returns the specified value.

expected: unknown: The expected return value.

Example: Usage

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

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

// expect(mock).toReturnWith(42);
expect(mock).not.toReturnWith(43);

`toStrictEqual`

toStrictEqual(candidate: unknown): void

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

candidate: unknown: The candidate value.

Example: Usage

import { expect } from "@ende/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 extends Error = Error>(expected?: string | RegExp | E | (new (...args: any[]) => E)): void

Asserts that the function throws an error.

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

Example: Usage

import { expect } from "@ende/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/);

Source