Test API

type AsymmetricMatcher = {
		readonly __maligator_asymmetric__: string;
	};

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

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

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

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

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