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

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

import { type CustomOutputAsserter } from '@augment-vir/assert';
import { type RemoveFirstTupleEntry, type TypedFunction } from '@augment-vir/core';
import { type BaseTestCase } from './it-cases.js';
import { type UniversalTestContext } from './universal-test-context.js';
/**
 * Base function under test type for all test cases that pass in the test context.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type BaseFunctionWithContext = (testContext: Readonly<UniversalTestContext>, ...args: any[]) => any;
/**
 * Input for a test function with context 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 FunctionWithContextTestCaseSingleInput<FunctionToTest extends BaseFunctionWithContext> = {
    input: Parameters<FunctionToTest>[1];
} & 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 FunctionWithContextTestCaseMultipleInputs<FunctionToTest extends BaseFunctionWithContext> = {
    inputs: Parameters<FunctionToTest>['length'] extends never ? FunctionToTest extends TypedFunction<[
        UniversalTestContext,
        ...infer ArgumentsType
    ], any> ? ArgumentsType[] : never : RemoveFirstTupleEntry<Parameters<FunctionToTest>>;
} & BaseTestCase<Awaited<ReturnType<FunctionToTest>>>;
/**
 * A function test case used for {@link itCasesWithContext}.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type FunctionWithContextTestCase<FunctionToTest extends BaseFunctionWithContext> = 2 extends Parameters<FunctionToTest>['length'] ? Parameters<FunctionToTest>['length'] extends 1 | 2 ? FunctionWithContextTestCaseSingleInput<FunctionToTest> : FunctionWithContextTestCaseMultipleInputs<FunctionToTest> : 1 extends Parameters<FunctionToTest>['length'] ? BaseTestCase<Awaited<ReturnType<FunctionToTest>>> : FunctionWithContextTestCaseMultipleInputs<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 itCasesWithContext<const FunctionToTest extends BaseFunctionWithContext>(this: void, functionToTest: FunctionToTest, testCases: ReadonlyArray<FunctionWithContextTestCase<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 itCasesWithContext<const FunctionToTest extends BaseFunctionWithContext>(this: void, functionToTest: FunctionToTest, customAsserter: CustomOutputAsserter<NoInfer<FunctionToTest>>, testCases: ReadonlyArray<FunctionWithContextTestCase<NoInfer<FunctionToTest>>>): unknown[];