@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 { type SelectFrom } from '@augment-vir/common';
import { type PlaywrightTestArgs, type PlaywrightTestOptions, type PlaywrightWorkerArgs, type PlaywrightWorkerOptions, type TestInfo } from '@playwright/test';
import { type TestContext as NodeTestContextImport } from 'node:test';
import { type MochaTestContext } from './mocha-types.js';
/**
 * 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;
    };
};
/**
 * The test context for Playwright tests.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type PlaywrightTestContext = SelectFrom<PlaywrightTestArgs & PlaywrightTestOptions & PlaywrightWorkerArgs & PlaywrightWorkerOptions, {
    page: true;
    baseURL: true;
    browser: true;
    context: true;
    extraHTTPHeaders: true;
    viewport: true;
    video: true;
    userAgent: true;
    timezoneId: true;
    serviceWorkers: true;
    screenshot: true;
    isMobile: true;
    headless: true;
    hasTouch: true;
}> & {
    testInfo: TestInfo;
    testName: {
        /** Clean, easily readable for humans. */
        clean: string;
        /** Unique with a random slug appended. */
        unique: string;
    };
};
/**
 * Test context provided by `it`'s callback.
 *
 * Compatible with both [Node.js's test runner](https://nodejs.org/api/test.html),
 * [web-test-runner](https://modern-web.dev/docs/test-runner/overview/) or other Mocha-style test
 * runners, and Playwright's test runner.
 *
 * @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 | PlaywrightTestContext;
/**
 * Used to determine which test context is in use.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare enum TestEnv {
    Node = "node",
    Web = "web",
    Playwright = "playwright"
}
/**
 * Test context by the env they run in.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export type TestContextByEnv = {
    [TestEnv.Node]: NodeTestContext;
    [TestEnv.Web]: MochaTestContext;
    [TestEnv.Playwright]: PlaywrightTestContext;
};
/**
 * 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;
/**
 * Same as {@link extractTestName} but sanitizes the output so that it's safe for directory names
 * (even on Windows).
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function extractTestNameAsDir(testContext: UniversalTestContext): string;
/**
 * Same as {@link extractTestNameAsDir} but sanitizes any input in the same way.
 *
 * @category Test : Util
 * @category Package : @augment-vir/test
 * @package [`@augment-vir/test`](https://www.npmjs.com/package/@augment-vir/test)
 */
export declare function cleanTestNameAsDir(testName: string): 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 TestEnv>(this: void, context: Readonly<UniversalTestContext>, env: SpecificEnv): TestContextByEnv[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 TestEnv>(this: void, context: Readonly<UniversalTestContext>, env: SpecificEnv): asserts context is TestContextByEnv[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 TestEnv>(this: void, context: Readonly<UniversalTestContext>, env: SpecificEnv): context is TestContextByEnv[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): TestEnv;