@epic-web/app-launcher/build/define-launcher.d.ts

Utility for launching your applications on a per-test basis.

import type { ChildProcess } from 'node:child_process';
import { AppProcess } from './app-process.js';
export interface LauncherInit<Context, Env extends Record<string, string>> {
    /**
     * Provide a launcher to extend.
     * When extended, the base launcher options, like `env`,
     * will be inherited by the new launcher.
     */
    extends?: Launcher;
    /**
     * Run the launcher in debug mode.
     */
    debug?: boolean;
    /**
     * Define a context object exposed to the other launcher methods.
     *
     * @example
     * defineLauncher({
     *   async context() {
     *     return { port: await getRandomPort() }
     *   }
     * })
     */
    context?: () => Context | Promise<Context>;
    /**
     * Define environment variables for this launcher.
     * Environment variables will be forwarded to the run `command`
     * automatically.
     *
     * @example
     * defineLauncher({
     *   env() {
     *     return { FOO: 'bar' }
     *   }
     * })
     */
    env?: (options: {
        context: Context;
    }) => Env | Promise<Env>;
    /**
     * Define a command that runs your application.
     *
     * @example
     * defineLauncher({
     *   command() {
     *     return `npm start`
     *   }
     * })
     */
    command: (options: {
        context: Context;
        env: Env;
    }) => string | Promise<string>;
    /**
     * Return the resolved application URL.
     *
     * @example
     * defineLauncher({
     *   url({ context }) {
     *     return `http://localhost:${context.port}`
     *   }
     * })
     */
    url: (options: {
        context: Context;
        env: Env;
        appProcess: ChildProcess;
    }) => string | URL | Promise<string | URL>;
}
export interface Launcher<Context = any> {
    [kLauncherOptions]: LauncherInit<Context, any>;
    run: (runOptions?: RunOptions<Context>) => Promise<AppProcess>;
}
export interface RunOptions<Context = any> {
    cwd?: string;
    env?: (options: {
        context: Context;
    }) => Record<string, string> | Promise<Record<string, string>>;
}
export declare const kLauncherOptions: unique symbol;
export declare function defineLauncher<Context, Env extends Record<string, string> = {}>(options: LauncherInit<Context, Env>): Launcher<Context>;