@ethaks/fvtt-quench/lib/quench.d.ts

Types for a Foundry VTT module enabling tests using Mocha and Chai

import * as fc from "fast-check";
import { QuenchResults } from "./apps/quench-results";
import { QuenchSnapshotManager } from "./quench-snapshot";
import * as quenchUserUtils from "./utils/user-utils";
declare global {
    namespace Mocha {
        interface Runnable {
            _quench_parentBatch?: string;
        }
        interface Suite {
            _quench_parentBatch?: string;
            _quench_batchRoot?: boolean;
            get id(): string;
        }
        interface Test {
            get id(): string;
        }
    }
}
/**
 * The `Quench` class is the "hub" of the Quench module. It contains the primary public API for Quench, as well as references to the global
 * mocha and chai objects.
 *
 * @public
 */
export declare class Quench {
    /**
     * Mocha's browser global
     *
     * @see https://mochajs.org/
     */
    readonly mocha: BrowserMocha;
    /**
     * Chai's static object
     *
     * @see https://www.chaijs.com/
     */
    readonly chai: Chai.ChaiStatic;
    /**
     * fast-check for property based testing
     *
     * @see https://fast-check.dev/
     * @see https://fast-check.dev/api-reference/index.html
     */
    readonly fc: typeof fc;
    /** Various utility functions */
    readonly utils: {
        [Util in keyof typeof quenchUserUtils]: (typeof quenchUserUtils)[Util];
    };
    /**
     * The singleton instance of {@link QuenchResults} that this `Quench` instance uses
     *
     * @internal
     */
    readonly app: QuenchResults;
    /**
     * The {@link QuenchSnapshotManager} instance that this `Quench` instance uses
     *
     * @internal
     */
    readonly snapshots: QuenchSnapshotManager;
    /**
     * A map of registered test batches
     *
     * @internal
     */
    readonly _testBatches: Collection<QuenchBatchData>;
    /**
     * The current Mocha runner, if any
     *
     * @internal
     */
    _currentRunner: Mocha.Runner | undefined;
    /**
     * An object holding reports generated by the last run.
     *
     * @public
     */
    reports: QuenchReports | Record<string, never>;
    /** @internal */
    constructor();
    /**
     * Filters {@link _testBatches} according to a given filter using [wildcard-match](https://github.com/axtgr/wildcard-match).
     *
     * @internal
     * @param pattern - The filter pattern
     * @param preSelectedOnly - If true, only batches that are preselected will be included
     * @returns A list of batch keys that match the filter
     */
    _filterBatches(pattern: string | string[], { preSelectedOnly }?: {
        preSelectedOnly?: boolean | undefined;
    }): QuenchBatchKey[];
    /**
     * Registers a new Quench test batch which will show up in the quench window to be enabled/disabled and run.
     *
     * Suites and tests within a Quench test batch are not actually registered in the mocha runner until the user initiates the test run
     * with {@link runBatches}. When `runBatches` is executed, the provided batches' registration functions
     * are run and then the tests are executed.
     *
     * The registration function is passed a `context` argument, which contains the mocha and chai methods necessary for defining a test.
     * - Mocha - `describe`, `it`, `after`, `afterEach`, `before`, `beforeEach`, and `utils`.
     * - Chai - `assert`, `expect`, and `should`; the last one is also made available by extending `Object.prototype`.
     * - fast-check - `fc`
     *
     * @param key - The test batch's unique string key. Only one test batch with a given key can exist at one time.
     *     If you register a test batch with a pre-existing key, it will overwrite the previous test batch.
     * @param fn - The function which will be called to register the suites and tests within your test batch.
     * @param context - Additional options affecting Quench's handling of this batch.
     * @example
     * quench.registerBatch(
     *  "quench.examples.basic-pass",
     *  (context) => {
     *    const { describe, it, assert } = context;
     *
     *    describe("Passing Suite", function () {
     *      it("Passing Test", function () {
     *        assert.ok(true);
     *      });
     *    });
     *  },
     *  {
     *    displayName: "QUENCH: Basic Passing Test",
     *    preSelected: true,
     *    snapBaseDir: "quench",
     *  },
     *);
     */
    registerBatch(key: QuenchBatchKey, fn: QuenchRegisterBatchFunction, context?: QuenchRegisterBatchOptions): void;
    /**
     * Runs the test batches defined by the keys in their {@link Quench.registerBatch | registration}.
     *
     * The contents of the test batches are registered with mocha when this function is executed.
     *
     * @example Running all batches
     * ```js
     * quench.runBatches(); // or
     * quench.runBatches("**");
     * ```
     * @example Running a single batch
     * ```js
     * quench.runBatches("quench.examples.basic-pass");
     * ```
     * @example Running multiple batches
     * ```js
     * quench.runBatches(["quench.examples.basic-pass", "quench.examples.basic-fail"]);
     * quench.runBatches("quench.examples.*"); // Will run "quench.examples.basic-pass", but not "quench.complex.basic-pass"
     * ```
     * @example Running all batches belonging to Quench
     * ```js
     * quench.runBatches("quench.**"); // or
     * quench.runBatches(["quench.**"]);
     * ```
     * @param [keys] - A single batch key or an array of batch keys to run.
     *
     *   Simple wildcards are supported:
     *   - `?` matches one arbitrary character, excluding the separator `.`
     *   - `*` matches zero or more arbitrary characters, excluding the separator `.`
     *   - `**` matches zero or more arbitrary characters, including the separator `.`
     * @param [options] - Additional options affecting this batch run
     * @returns Returns the mocha Runner object for this test run.
     */
    runBatches(keys?: string | string[], options?: QuenchRunBatchOptions): Promise<Mocha.Runner>;
    /**
     * Aborts the currently running tests, if tests are currently running. Does nothing if no tests are currently running.
     * This will not cancel an in progress test. The run will abort after the currently running test completes.
     *
     * @public
     */
    abort(): void;
}
/**
 * Optional data used in the batch registration process
 *
 * @public
 */
export interface QuenchRegisterBatchOptions {
    /**
     * A user-friendly name to show in the Quench UI and detailed results.
     * @defaultValue Defaults to the registration {@link QuenchBatchKey}
     */
    displayName?: string;
    /**
     * The directory in which snapshots for this batch are stored.
     * @defaultValue `__snapshots__/${PACKAGE_NAME}`, where `PACKAGE_NAME` is taken from the `key` parameter
     */
    snapBaseDir?: string;
    /**
     * Whether this batch should be checked when added to the UI, and possibly run on startup
     * if that setting is enabled.
     * @defaultValue `true`
     */
    preSelected?: boolean;
}
/**
 * A function containing this batch's suites and tests.
 * Before each Quench run including this batch, this function will be called by Quench.
 *
 * @public
 * @param context - Various Mocha and Chai functions
 */
export type QuenchRegisterBatchFunction = (this: Mocha.Suite, context: QuenchBatchContext) => void | Promise<void>;
/**
 * A context object passed to batch registration functions, containing functions usually
 * imported or globally available in regular Node testing.
 * Includes Mocha, Chai, and fast-check.
 *
 * @see https://mochajs.org/#bdd
 * @see https://www.chaijs.com/
 * @see https://fast-check.dev/api-reference/index.html
 *
 * @public
 */
export interface QuenchBatchContext {
    /** @see https://mochajs.org/#hooks */
    after: Mocha.HookFunction;
    /** @see https://mochajs.org/#hooks */
    afterEach: Mocha.HookFunction;
    /** @see https://mochajs.org/#hooks */
    before: Mocha.HookFunction;
    /** @see https://mochajs.org/#hooks */
    beforeEach: Mocha.HookFunction;
    utils: typeof Mocha.utils;
    /** @see https://www.chaijs.com/api/assert/#method_assert */
    assert: Chai.AssertStatic;
    /** @see https://www.chaijs.com/api/bdd/ */
    expect: Chai.ExpectStatic;
    /** @see https://www.chaijs.com/api/bdd/ */
    should: Chai.Should;
    /** @see https://mochajs.org/#bdd */
    describe: Mocha.SuiteFunction;
    /** @see https://mochajs.org/#bdd */
    it: Mocha.TestFunction;
    /** @see https://fast-check.dev/api-reference/index.html */
    fc: typeof fc;
}
/**
 * Options affecting the running of batches
 *
 * @public
 */
export interface QuenchRunBatchOptions {
    /**
     * Whether snapshots generated in this run should be saved
     *
     * @defaultValue `null`
     */
    updateSnapshots?: boolean | null;
    /**
     * Whether only batches registered with {@link QuenchRegisterBatchOptions.preSelected}
     * set to `true` should be run.
     *
     * @defaultValue `false`
     */
    preSelectedOnly?: boolean;
    /**
     * Generate a JSON report.
     *
     * - If `false`, a JSON report will be generated and made available in {@link Quench.reports quench.reports},
     *   as well as through the {@link hookEvents!quenchReports} hook.
     * - If `true`, a JSON report will be generated as above,
     *   and also be uploaded to the server as `Data/quench-report.json`, overwriting any existing file.
     *   Option defaults can be found in {@link QuenchJsonReportOptions}.
     * - If an object is provided, additional options can be set.
     *
     * @defaultValue `false`
     */
    json?: boolean | QuenchJsonReportOptions;
}
/**
 * Options affecting Quench's JSON report generation and availability.
 *
 * @public
 */
export interface QuenchJsonReportOptions {
    /**
     * The path to which the JSON report will be uploaded.
     *
     * @defaultValue `quench-report.json`
     */
    filename?: string;
}
/**
 * The key by which a test batch is identified.
 * The key should consist of the registering package's `id` from its manifest,
 * followed by a `.`, and then the batch's individual identifier.
 *
 * @public
 */
export type QuenchBatchKey = `${string}.${string}`;
/**
 * Data belonging to a single batch, including its registration function and any
 * additional options.
 *
 * @public
 */
export interface QuenchBatchData {
    key: QuenchBatchKey;
    fn: QuenchRegisterBatchFunction;
    displayName: string;
    snapBaseDir: string;
    preSelected: boolean;
}
/**
 * An object containing all reports generated after a batch run.
 *
 * @public
 */
export interface QuenchReports {
    /**
     * The JSON report of the last run, if available.
     *
     * Before being stringified, the report data has a format of {@link QuenchJsonReport}.
     */
    json: string;
}