web-snaps/dist/snap-suite/snap-suite.d.ts

Browser automation with automatic snapshotting.

import { type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
import { type BrowserOptions } from '../browser/init-browser.js';
import { type LoadedBrowser } from '../browser/loaded-browser.js';
import { type BrowserSetupParams } from '../browser/run-browser.js';
import { type RunWebFlowOptions, type RunWebFlowParams } from '../web-flow/run-web-flow.js';
import { type WebFlow, type WebFlowInit } from '../web-flow/web-flow.js';
/**
 * Options for {@link runWebFlows}.
 *
 * @category Internal
 */
export type RunWebFlowsOptions = PartialWithUndefined<{
    /** Runs before the WebFlows start. */
    preHook: (params: Readonly<Pick<LoadedBrowser<any>, 'browserContext'>>) => MaybePromise<void>;
    /** Runs after the WebFlows finish, even if they error out. */
    postHook: (params: Readonly<Pick<LoadedBrowser<any>, 'browserContext'> & {
        /** If any WebFlow errored out, this is populated with that error. */
        error?: undefined | Error;
    }>) => MaybePromise<void>;
    browserOptions: Readonly<BrowserOptions>;
}> & {
    userDataDirPath: string;
} & RunWebFlowOptions & ({
    /**
     * Run all given WebFlows in serial rather than in parallel. By default, all WebFlows
     * are executed in parallel.
     *
     * @default false
     */
    serial?: undefined | false;
    /**
     * Number of WebFlows to run at once (in parallel). Only relevant when `serial` is not
     * set to `true`.
     *
     * @default 10
     */
    batchSize: number;
} | {
    /**
     * Run all given WebFlows in serial rather than in parallel. By default, all WebFlows
     * are executed in parallel.
     *
     * @default false
     */
    serial: true;
    /**
     * Number of WebFlows to run at once (in parallel). Only relevant when `serial` is not
     * set to `true`.
     *
     * @default 10
     */
    batchSize?: never;
});
/**
 * The output of {@link defineSnapSuite}.
 *
 * @category Internal
 */
export type SnapSuite<Context, Output> = {
    /**
     * Defines a {@link WebFlow} with the suite's `Context` and `Output` type parameters and
     * `webSnapDirPath` option already set.
     */
    defineWebFlow<const Init extends Readonly<WebFlowInit<Context, Output>>>(this: void, init: Init): WebFlow<Context, Output, Init>;
    /**
     * Executes a single {@link WebFlow} with the suite's `Context` and `Output` type parameters and
     * `webSnapDirPath` option already set.
     */
    runWebFlow(this: void, params: RunWebFlowParams<Context, Output>): Promise<(Output | undefined)[]>;
    /**
     * Executes multiple {@link WebFlow} instances with the suite's `Context` and `Output` type
     * parameters and `webSnapDirPath` option already set.
     */
    runWebFlows(this: void, params: RunWebFlowsParams<Context, Output>): Promise<(Output | undefined)[][]>;
    /** Runs {@link withBrowserContext} with the suite's `Context` type parameter already set. */
    withBrowserContext<T = void>(this: void, params: BrowserSetupParams<Context>, 
    /** Calls this callback and then automatically closes the browser afterwards. */
    callback: (params: Readonly<LoadedBrowser<Context>>) => MaybePromise<T>): Promise<T>;
    /** Runs {@link setupBrowser} with the suite's `Context` type parameter already set. */
    setupBrowser(this: void, params: BrowserSetupParams<Context>): Promise<LoadedBrowser<Context>>;
};
/**
 * Define a suite of WebFlow functions with already set type parameters.
 *
 * @category Main
 */
export declare function defineSnapSuite<Context, Output>(this: void, 
/** Output directory for saved snapshots. Setting this to `undefined` disables snapshots. */
webSnapDirPath: string | undefined): SnapSuite<Context, Output>;
/**
 * Params for {@link runWebFlows}.
 *
 * @category Internal
 */
export type RunWebFlowsParams<Context, Output> = {
    context: Context;
    webFlows: ReadonlyArray<Readonly<WebFlow<Context, Output>>>;
    userDataDirPath: string;
    options?: Readonly<Omit<RunWebFlowsOptions, 'userDataDirPath'>> | undefined;
};
/**
 * Runs an array of {@link WebFlow} instances. Use {@link defineSnapSuite} instead of calling this
 * function directly for cleaner Type Parameter inference.
 *
 * @category Internal
 */
export declare function runWebFlows<Context, Output>({ context, userDataDirPath, webFlows, options, }: Readonly<RunWebFlowsParams<Context, Output>>): Promise<(Output | undefined)[][]>;
/**
 * Define a full {@link WebFlow}. Use {@link defineSnapSuite} instead of calling this function
 * directly for cleaner Type Parameter inference.
 *
 * @category Internal
 */
export declare function defineWebFlow<Context, Output, const Init extends Readonly<WebFlowInit<Context, Output>>>(this: void, init: Init, 
/** Directory path for saved snapshots. */
webSnapDirPath: string | undefined): WebFlow<Context, Output, Init>;