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

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

import { RuntimeEnv } from '@augment-vir/core';
import { type TestContext as NodeTestContextImport } from 'node:test';
import { type MochaTestContext } from './mocha-types.js';
export { RuntimeEnv } from '@augment-vir/core';
/**
 * The test context for [Node.js's test runner](https://nodejs.org/api/test.html).
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type NodeTestContext = Readonly<NodeTestContextImport> & {
    /** Added for use by `assertSnapshot`. */
    snapshotCount?: {
        [TestName in string]: number;
    };
};
/**
 * Test context provided by `it`'s callback.
 *
 * 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 : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type UniversalTestContext = NodeTestContext | MochaTestContext;
/**
 * Test context by runtime env when [Node.js's test runner](https://nodejs.org/api/test.html) is
 * used for Node tests and [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) is
 * used for web tests.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type ContextByEnv = {
    [RuntimeEnv.Node]: NodeTestContext;
    [RuntimeEnv.Web]: MochaTestContext;
};
/**
 * Extracts the full test name (including parent describes) of a given test context. Whether the
 * test be run in web or node tests, the name will be the same.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function extractTestName(testContext: UniversalTestContext): string;
/**
 * Asserts that the given context is for the given env and returns that context.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @throws `TypeError` if the context does not match the env.
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function assertWrapTestContext<const SpecificEnv extends RuntimeEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): ContextByEnv[SpecificEnv];
/**
 * Asserts that the given context is for the given env, otherwise throws an Error.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function assertTestContext<const SpecificEnv extends RuntimeEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): asserts context is ContextByEnv[SpecificEnv];
/**
 * Checks that the given context is for the given env.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function isTestContext<const SpecificEnv extends RuntimeEnv>(this: void, context: UniversalTestContext, env: SpecificEnv): context is ContextByEnv[SpecificEnv];
/**
 * Determine the env for the given test context.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function determineTestContextEnv(this: void, context: UniversalTestContext): RuntimeEnv;