projen/lib/javascript/node-native-test-runner.d.ts

CDK for software projects

import type { IConstruct } from "constructs";
import { Component } from "../component";
import type { Project } from "../project";
import type { NodeConfigSchemaNodeOptions, NodeConfigSchemaTest } from "./node-config";
import { NodeConfigFile } from "./node-config-file";
import { NodeProject } from "./node-project";
/**
 * Whether to update snapshots in task "test" (which is executed in task
 * "build" and build workflows), or create a separate task "test:update" for
 * updating snapshots.
 */
export declare enum NodeTestUpdateSnapshot {
    /**
     * Always update snapshots in "test" task.
     */
    ALWAYS = "always",
    /**
     * Never update snapshots in "test" task and create a separate "test:update" task.
     */
    NEVER = "never"
}
export type ReporterKind = "dot" | "junit" | "lcov" | "spec" | "tap";
/**
 * Where a reporter's output is written.
 *
 * @see https://nodejs.org/api/test.html#test-reporters
 */
export declare class Destination {
    /**
     * The underlying value: `"stdout"`, `"stderr"`, or a file path.
     */
    readonly value: string;
    /**
     * Write to standard output.
     */
    static readonly STDOUT: Destination;
    /**
     * Write to standard error.
     */
    static readonly STDERR: Destination;
    /**
     * Write to a file at the given path.
     * @param path path of the file to write to
     */
    static file(path: string): Destination;
    private constructor();
}
/**
 * A single reporter/destination pair for the Node.js native test runner.
 *
 * @see https://nodejs.org/api/test.html#test-reporters
 */
export interface NodeReporter {
    /**
     * The name/kind of the reporter.
     */
    readonly name: ReporterKind;
    /**
     * Where the reporter's output is written.
     *
     * @see https://github.com/nodejs/node/blob/4215cc35e25c44f9f4fea5a4541afc862db7ef0a/test/parallel/test-runner-reporters.js#L46-L77
     * @default Destination.STDOUT
     */
    readonly destination: Destination;
}
/**
 * Options for Node.js' built-in test runner (`node --test`).
 */
export interface NodeNativeTestRunnerOptions {
    /**
     * The directory where coverage files are output, if coverage collection
     * is enabled.
     *
     * @default "coverage"
     */
    readonly coverageDirectory?: string;
    /**
     * Whether to update snapshots in task "test" (which is executed in task
     * "build" and build workflows), or create a separate task "test:update"
     * for updating snapshots.
     *
     * @default - ALWAYS
     */
    readonly updateSnapshot?: NodeTestUpdateSnapshot;
    /**
     * Additional options to pass to the `node --test` CLI invocation.
     *
     * Each element is passed as a single argument, exactly as given: no shell
     * parses these, so a flag and its value need separate elements
     * (`["--foo", "bar"]`, not `["--foo bar"]`).
     *
     * @default - no extra options
     */
    readonly extraCliOptions?: string[];
    /**
     * Preserve the default reporters (`spec`, `lcov`, `junit`) when additional
     * reporters are added.
     *
     * @default true
     */
    readonly preserveDefaultReporters?: boolean;
    /**
     * Additional reporters to configure (e.g. `{ name: "tap", destination:
     * Destination.file("test-reports/tap.txt") }`).
     *
     * These are added on top of the default reporters (`spec`, `lcov`, `junit`),
     * which are controlled via `collectCoverage`. Use
     * `NodeNativeTestRunner.addReporter`/`removeReporter`/`listReporters` to
     * manage reporters after construction.
     *
     * @default - no additional reporters
     */
    readonly reporters?: NodeReporter[];
    /**
     * Path to the JSON configuration file for the test runner.
     *
     * @default "node.config.json"
     */
    readonly configFilePath?: string;
    /**
     * Glob patterns matching the files that contain tests. By default it
     * combines Node.js' own default test file discovery with Jest conventions.
     *
     * @default - combines Node.js' own default test file discovery with Jest conventions
     */
    readonly testMatch?: string[];
    /**
     * Indicates whether the coverage information should be collected while
     * executing the test, via `--experimental-test-coverage`.
     *
     * @default true
     */
    readonly collectCoverage?: boolean;
    /**
     * An array of glob patterns that are matched against all file paths before
     * executing coverage collection. If a file path matches any of the
     * patterns, coverage information will be skipped for it.
     *
     * @default ["**\/test/**", "**\/__tests__/**"]
     */
    readonly coveragePathIgnorePatterns?: string[];
    /**
     * This option allows the use of a custom global setup module which
     * exports a function that is triggered once before all test suites.
     * Written as `test-global-setup` in the generated Node.js configuration
     * file.
     *
     * @default - undefined
     */
    readonly globalSetup?: string;
    /**
     * Enable module mocking support via `--experimental-test-module-mocks`.
     *
     * @default false
     */
    readonly moduleMocks?: boolean;
    /**
     * Whether to enable transformation of TypeScript-only syntax (e.g. enums, namespaces).
     *
     * Uses `amaro` (the TypeScript transformer used internally by Node.js) as an
     * external loader via `--import=amaro/transform`. Adds a dependency on the
     * `amaro` package and enables `--enable-source-maps` to preserve accurate
     * stack traces.
     *
     * @see https://github.com/nodejs/amaro
     * @default false
     */
    readonly transformTypes?: boolean;
    /**
     * Additional entries for the `nodeOptions` section of the generated
     * configuration file (e.g. `enableSourceMaps`, `disableWarning`).
     *
     * @default - no additional node options
     */
    readonly nodeOptions?: NodeConfigSchemaNodeOptions;
    /**
     * Additional entries for the `test` section of the generated
     * configuration file (e.g. `testConcurrency`, `testTimeout`).
     *
     * @default - no additional options
     */
    readonly testConfig?: NodeConfigSchemaTest;
}
/**
 * Configures Node's built-in test runner (`node --test`).
 *
 * Owns the generated Node.js configuration file, the "test", "test:update"
 * and "test:watch" tasks, and the reporters and test match patterns they use.
 */
export declare class NodeNativeTestRunner extends Component {
    /**
     * Returns the singleton NodeNativeTestRunner component of a project or undefined
     * if there is none.
     */
    static of(project: Project): NodeNativeTestRunner | undefined;
    readonly project: NodeProject;
    private readonly coverageDirectory?;
    private readonly updateSnapshot;
    private readonly reporters;
    /**
     * The generated Node.js configuration file.
     */
    readonly configFile: NodeConfigFile;
    private readonly testReportsDir;
    private readonly testMatch;
    constructor(scope: IConstruct, options?: NodeNativeTestRunnerOptions);
    /**
     * Adds a test match pattern.
     * @param pattern glob pattern to match for tests
     */
    addTestMatch(pattern: string): void;
    /**
     * Removes a test match pattern, if configured.
     * @param pattern glob pattern to remove
     */
    removeTestMatch(pattern: string): void;
    /**
     * Adds a reporter, or updates its destination if one with the same name
     * is already configured.
     * @param name The name/kind of the reporter, e.g. `spec`, `junit`, `lcov`.
     * @param destination Where the reporter's output is written.
     * @default Destination.STDOUT
     */
    addReporter(name: ReporterKind, destination?: Destination): void;
    /**
     * Removes a reporter, if configured.
     * @param name The name/kind of the reporter to remove.
     */
    removeReporter(name: ReporterKind): void;
    /**
     * Lists the configured reporters, in the order they were added.
     */
    listReporters(): NodeReporter[];
}