maligator:test

Test authoring and assertions. Importing this module does not register tests or install runner globals. Registration and assertions are ordinary effectful calls; the test command initializes its internal runner explicitly. Unused imports can be eliminated.

Status: experimental. Module evaluation: side-effect-free.

TypeScript: include @maligator/cli in your tsconfig compilerOptions.types or add /// <reference types="@maligator/cli" /> to a declaration file.

test

Register a test in the current suite.

Phase: runtime. Value: callable. Identity: module.

describe

Register a nested suite in the current suite.

Phase: runtime. Value: callable. Identity: module.

expect

Create fluent matchers for a received value.

Phase: runtime. Value: callable. Identity: module.

beforeAll

Run once before tests in the current suite.

Phase: runtime. Value: callable. Identity: module.

afterAll

Run once after tests in the current suite, including after test failures.

Phase: runtime. Value: callable. Identity: module.

beforeEach

Run before every selected descendant test. Ancestor hooks run before hooks declared by a nested suite.

Phase: runtime. Value: callable. Identity: module.

afterEach

Run after every selected descendant test. Nested-suite hooks run before ancestor hooks.

Phase: runtime. Value: callable. Identity: module.

TestCallback

A test or hook body. Maligator waits for a returned promise or thenable before advancing the lifecycle.

type TestCallback = () => unknown;

HookCallback

A lifecycle hook body, with the same async completion contract as a test.

type HookCallback = TestCallback;

Constructor

A constructable value accepted by expect.any.

type Constructor = abstract new (...args: Array<never>) => unknown;

AsymmetricMatcher

Opaque partial-match value produced by helpers such as expect.objectContaining. It may be nested inside toEqual, toStrictEqual, and toMatchObject expectations.

readonly __maligator_asymmetric__: string

TypeScript declaration

type AsymmetricMatcher = {
		readonly __maligator_asymmetric__: string;
	};

Matchers

Matchers for a synchronously received value.

readonly not: Matchers: Negate the following matcher.
readonly resolves: AsyncMatchers: Wait for the received promise to fulfill, then match its value.
readonly rejects: AsyncMatchers: Wait for the received promise to reject, then match its reason.
toBe(expected: unknown): void: Require ECMAScript Object.is identity.
toEqual(expected: unknown): void: Recursively compare enumerable object properties and array elements.
toStrictEqual(expected: unknown): void: Recursively compare values while also requiring matching prototypes and matching sparse-array holes.
toBeDefined(): void: Require a value other than undefined.
toBeUndefined(): void: Require undefined.
toBeNull(): void: Require null.
toBeTruthy(): void: Require a truthy value.
toBeFalsy(): void: Require a falsy value.
toContain(expected: unknown): void: Require a string substring or an array element matched by identity.
toHaveLength(expected: number): void: Require a numeric .length equal to expected.
toMatch(expected: string | RegExp): void: Match a string against a substring or regular expression.
toMatchObject(expected: object): void: Recursively require the enumerable properties present in expected.
toThrow( expected?: | string | RegExp | Error | (abstract new (...args: Array<never>) => Error), ): void: Invoke the received function and require it to throw. The optional expectation may be a message substring, regular expression, error constructor, or error instance.

TypeScript declaration

type Matchers = {
		/** Negate the following matcher. */
		readonly not: Matchers;
		/** Wait for the received promise to fulfill, then match its value. */
		readonly resolves: AsyncMatchers;
		/** Wait for the received promise to reject, then match its reason. */
		readonly rejects: AsyncMatchers;
		/** Require ECMAScript `Object.is` identity. */
		toBe(expected: unknown): void;
		/** Recursively compare enumerable object properties and array elements. */
		toEqual(expected: unknown): void;
		/**
		 * Recursively compare values while also requiring matching prototypes and
		 * matching sparse-array holes.
		 */
		toStrictEqual(expected: unknown): void;
		/** Require a value other than `undefined`. */
		toBeDefined(): void;
		/** Require `undefined`. */
		toBeUndefined(): void;
		/** Require `null`. */
		toBeNull(): void;
		/** Require a truthy value. */
		toBeTruthy(): void;
		/** Require a falsy value. */
		toBeFalsy(): void;
		/** Require a string substring or an array element matched by identity. */
		toContain(expected: unknown): void;
		/** Require a numeric `.length` equal to `expected`. */
		toHaveLength(expected: number): void;
		/** Match a string against a substring or regular expression. */
		toMatch(expected: string | RegExp): void;
		/** Recursively require the enumerable properties present in `expected`. */
		toMatchObject(expected: object): void;
		/**
		 * Invoke the received function and require it to throw. The optional
		 * expectation may be a message substring, regular expression, error
		 * constructor, or error instance.
		 */
		toThrow(
			expected?:
				| string
				| RegExp
				| Error
				| (abstract new (...args: Array<never>) => Error),
		): void;
	};

AsyncMatchers

Promise-returning matcher surface exposed by Matchers.resolves and Matchers.rejects. Await these calls so the test cannot finish before the assertion.

readonly not: AsyncMatchers: Negate the following asynchronous matcher.
toBe(expected: unknown): Promise<void>
toEqual(expected: unknown): Promise<void>
toStrictEqual(expected: unknown): Promise<void>
toBeDefined(): Promise<void>
toBeUndefined(): Promise<void>
toBeNull(): Promise<void>
toBeTruthy(): Promise<void>
toBeFalsy(): Promise<void>
toContain(expected: unknown): Promise<void>
toHaveLength(expected: number): Promise<void>
toMatch(expected: string | RegExp): Promise<void>
toMatchObject(expected: object): Promise<void>
toThrow( expected?: | string | RegExp | Error | (abstract new (...args: Array<never>) => Error), ): Promise<void>

TypeScript declaration

type AsyncMatchers = {
		/** Negate the following asynchronous matcher. */
		readonly not: AsyncMatchers;
		toBe(expected: unknown): Promise<void>;
		toEqual(expected: unknown): Promise<void>;
		toStrictEqual(expected: unknown): Promise<void>;
		toBeDefined(): Promise<void>;
		toBeUndefined(): Promise<void>;
		toBeNull(): Promise<void>;
		toBeTruthy(): Promise<void>;
		toBeFalsy(): Promise<void>;
		toContain(expected: unknown): Promise<void>;
		toHaveLength(expected: number): Promise<void>;
		toMatch(expected: string | RegExp): Promise<void>;
		toMatchObject(expected: object): Promise<void>;
		toThrow(
			expected?:
				| string
				| RegExp
				| Error
				| (abstract new (...args: Array<never>) => Error),
		): Promise<void>;
	};

ExpectFunction

Assertion entrypoint and Maligator-owned asymmetric matcher factories.

(received: unknown): Matchers: Create matchers for received. The assertion position is captured here.
any(constructorValue: Constructor): AsymmetricMatcher: Match a primitive of the corresponding built-in kind or an instance.
anything(): AsymmetricMatcher: Match any value except null and undefined.
stringMatching(pattern: string | RegExp): AsymmetricMatcher: Match a string containing pattern or satisfying the regular expression.
objectContaining(value: object): AsymmetricMatcher: Match an object containing all recursively matched properties in value.
arrayContaining(value: Array<unknown>): AsymmetricMatcher: Match an array containing a match for every element in value.

TypeScript declaration

type ExpectFunction = {
		/** Create matchers for `received`. The assertion position is captured here. */
		(received: unknown): Matchers;
		/** Match a primitive of the corresponding built-in kind or an instance. */
		any(constructorValue: Constructor): AsymmetricMatcher;
		/** Match any value except `null` and `undefined`. */
		anything(): AsymmetricMatcher;
		/** Match a string containing `pattern` or satisfying the regular expression. */
		stringMatching(pattern: string | RegExp): AsymmetricMatcher;
		/** Match an object containing all recursively matched properties in `value`. */
		objectContaining(value: object): AsymmetricMatcher;
		/** Match an array containing a match for every element in `value`. */
		arrayContaining(value: Array<unknown>): AsymmetricMatcher;
	};

TestFunction

Register tests in the current suite during module evaluation.

(name: string, callback: TestCallback): void: Register a test. Returned promises are awaited by the runner.
skip(name: string, callback: TestCallback): void: Register a skipped test without invoking its callback.
todo(name: string): void: Register a named placeholder with no callback.
only(name: string, callback: TestCallback): void: Register a focused test. When any .only exists, non-focused tests are skipped and the runner emits a warning.
each<const Row extends ReadonlyArray<unknown>>( rows: ReadonlyArray<Row>, ): (name: string, callback: (...values: [...Row]) => unknown) => void: Register one test for each row. Use %# in name for the zero-based row index. Array rows are spread into callback parameters.

TypeScript declaration

type TestFunction = {
		/** Register a test. Returned promises are awaited by the runner. */
		(name: string, callback: TestCallback): void;
		/** Register a skipped test without invoking its callback. */
		skip(name: string, callback: TestCallback): void;
		/** Register a named placeholder with no callback. */
		todo(name: string): void;
		/**
		 * Register a focused test. When any `.only` exists, non-focused tests are
		 * skipped and the runner emits a warning.
		 */
		only(name: string, callback: TestCallback): void;
		/**
		 * Register one test for each row. Use `%#` in `name` for the zero-based row
		 * index. Array rows are spread into callback parameters.
		 */
		each<const Row extends ReadonlyArray<unknown>>(
			rows: ReadonlyArray<Row>,
		): (name: string, callback: (...values: [...Row]) => unknown) => void;
	};

DescribeFunction

Register nested suites synchronously during module evaluation.

(name: string, callback: () => void): void: Register a suite. Suite callbacks must not return a promise.
skip(name: string, callback: () => void): void: Register a suite whose descendants are skipped.
only(name: string, callback: () => void): void: Register a focused suite and emit the runner's focused-test warning.

TypeScript declaration

type DescribeFunction = {
		/** Register a suite. Suite callbacks must not return a promise. */
		(name: string, callback: () => void): void;
		/** Register a suite whose descendants are skipped. */
		skip(name: string, callback: () => void): void;
		/** Register a focused suite and emit the runner's focused-test warning. */
		only(name: string, callback: () => void): void;
	};