@augment-vir/test/dist/augments/universal-testing-suite/it-cases.d.ts

A universal testing suite that works with Mocha style test runners _and_ Node.js's built-in test runner.

import { type CustomOutputAsserter, type ErrorMatchOptions } from '@augment-vir/assert';
import { type AnyFunction, type TypedFunction } from '@augment-vir/core';
import { type RequireExactlyOne } from 'type-fest';
/**
 * Base test case for {@link itCases}.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type BaseTestCase<OutputGeneric> = {
    it: string;
    only?: boolean | undefined;
    skip?: boolean | undefined;
} & RequireExactlyOne<{
    expect: OutputGeneric;
    throws: ErrorMatchOptions | undefined;
}>;
/**
 * Input for a function test that only has a single input.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type FunctionTestCaseSingleInput<FunctionToTest extends AnyFunction> = {
    input: Parameters<FunctionToTest>[0];
} & BaseTestCase<Awaited<ReturnType<FunctionToTest>>>;
/**
 * Input for a function test that has multiple inputs.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type FunctionTestCaseMultipleInputs<FunctionToTest extends AnyFunction> = {
    inputs: Parameters<FunctionToTest>['length'] extends never ? FunctionToTest extends TypedFunction<[infer ArgumentsType], any> ? ArgumentsType[] : never : Parameters<FunctionToTest>;
} & BaseTestCase<Awaited<ReturnType<FunctionToTest>>>;
/**
 * A function test case used for {@link itCases}.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type FunctionTestCase<FunctionToTest extends AnyFunction> = 1 extends Parameters<FunctionToTest>['length'] ? Parameters<FunctionToTest>['length'] extends 0 | 1 ? FunctionTestCaseSingleInput<FunctionToTest> : FunctionTestCaseMultipleInputs<FunctionToTest> : 0 extends Parameters<FunctionToTest>['length'] ? BaseTestCase<Awaited<ReturnType<FunctionToTest>>> : FunctionTestCaseMultipleInputs<FunctionToTest>;
/**
 * Succinctly run many input / output tests for a pure function without repeating `it` boilerplate.
 * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
 * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
 * runners.
 *
 * @category Test
 * @category Package : @augment-vir/test
 * @example
 *
 * ```ts
 * import {itCases, describe} from '@augment-vir/test';
 *
 * function myFunctionToTest(a: number, b: number) {
 *     return a + b;
 * }
 *
 * describe(myFunctionToTest.name, () => {
 *     itCases(myFunctionToTest, [
 *         {
 *             it: 'handles negative numbers',
 *             inputs: [
 *                 -1,
 *                 -2,
 *             ],
 *             expect: -3,
 *         },
 *         {
 *             it: 'handles 0',
 *             inputs: [
 *                 0,
 *                 0,
 *             ],
 *             expect: 0,
 *         },
 *         {
 *             it: 'adds',
 *             inputs: [
 *                 3,
 *                 5,
 *             ],
 *             expect: 8,
 *         },
 *     ]);
 * });
 * ```
 *
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function itCases<const FunctionToTest extends AnyFunction>(this: void, functionToTest: FunctionToTest, testCases: ReadonlyArray<FunctionTestCase<NoInfer<FunctionToTest>>>): unknown[];
/**
 * Succinctly run many input / output tests for a pure function without repeating `it` boilerplate.
 * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html) and
 * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
 * runners.
 *
 * @category Test
 * @category Package : @augment-vir/test
 * @example
 *
 * ```ts
 * import {itCases, describe} from '@augment-vir/test';
 *
 * function myFunctionToTest(a: number, b: number) {
 *     return a + b;
 * }
 *
 * describe(myFunctionToTest.name, () => {
 *     itCases(myFunctionToTest, [
 *         {
 *             it: 'handles negative numbers',
 *             inputs: [
 *                 -1,
 *                 -2,
 *             ],
 *             expect: -3,
 *         },
 *         {
 *             it: 'handles 0',
 *             inputs: [
 *                 0,
 *                 0,
 *             ],
 *             expect: 0,
 *         },
 *         {
 *             it: 'adds',
 *             inputs: [
 *                 3,
 *                 5,
 *             ],
 *             expect: 8,
 *         },
 *     ]);
 * });
 * ```
 *
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function itCases<const FunctionToTest extends AnyFunction>(this: void, functionToTest: FunctionToTest, customAsserter: CustomOutputAsserter<NoInfer<FunctionToTest>>, testCases: ReadonlyArray<FunctionTestCase<NoInfer<FunctionToTest>>>): unknown[];