@holochain/tryorama/lib/scenario.d.ts

Toolset to manage Holochain conductors and facilitate running test scenarios

import { type AgentPubKey, AppBundleSource, AppWebsocket } from "@holochain/client";
import { ChildProcessWithoutNullStreams } from "node:child_process";
import { Conductor, NetworkConfig } from "./conductor.js";
import { AgentApp, AppOptions } from "./types.js";
/**
 * A player consists of a {@link Conductor} and an agent pub key.
 *
 * @public
 */
export interface Player {
    agentPubKey: AgentPubKey;
    conductor: Conductor;
}
/**
 * @public
 */
export interface PlayerApp extends Player, AgentApp {
    appWs: AppWebsocket;
}
/**
 * @public
 */
export interface AppWithOptions {
    appBundleSource: AppBundleSource;
    options?: AppOptions;
}
/**
 * Options when creating a scenario.
 *
 * @public
 */
export interface ScenarioOptions {
    timeout?: number;
    disableLocalServices?: boolean;
}
/**
 * An abstraction of a test scenario to write tests against Holochain hApps,
 * running on a local conductor.
 *
 * @public
 */
export declare class Scenario {
    private timeout;
    noDpki: boolean;
    dpkiNetworkSeed: string;
    networkSeed: string;
    disableLocalServices: boolean | undefined;
    serviceProcess: ChildProcessWithoutNullStreams | undefined;
    bootstrapServerUrl: URL | undefined;
    signalingServerUrl: URL | undefined;
    conductors: Conductor[];
    /**
     * Scenario constructor.
     *
     * @param options - Timeout for requests to Admin and App API calls.
     */
    constructor(options?: ScenarioOptions);
    /**
     * Create and add a conductor to the scenario.
     *
     * @returns The newly added conductor instance.
     */
    addConductor(): Promise<Conductor>;
    /**
     * Create conductors with agents and add them to the scenario.
     *
     * The specified number of conductors is created and one agent is
     * generated on each conductor.
     *
     * @param amount - The number of players to be created.
     * @param networkConfig - Optional {@link NetworkConfig}
     * @returns An array of {@link Player}s
     */
    addPlayers(amount: number, networkConfig?: NetworkConfig): Promise<Player[]>;
    /**
     * Installs the provided apps for the provided players.
     *
     * The number of players must be at least as high as the number of apps.
     *
     * # Errors
     *
     * If any of the app options contains an agent pub key, an error is thrown,
     * because the agent pub keys of the players will be used for app installation.
     *
     * @param appsWithOptions - The apps with options to be installed
     * @param players - The players the apps are installed for
     * @returns An array of player apps.
     */
    installAppsForPlayers(appsWithOptions: AppWithOptions[], players: Player[]): Promise<PlayerApp[]>;
    /**
     * Installs the same provided app for the provided players.
     *
     * @param appsWithOptions - The app with options to be installed for all players
     * @param players - The players the apps are installed for
     * @returns An array of player apps.
     */
    installSameAppForPlayers(appWithOptions: AppWithOptions, players: Player[]): Promise<PlayerApp[]>;
    /**
     * Create and add a single player with an app installed to the scenario.
     *
     * @param appBundleSource - The bundle or path to the bundle.
     * @param options - {@link AppOptions}.
     * @returns A player with the installed app.
     */
    addPlayerWithApp(appWithOptions: AppWithOptions): Promise<PlayerApp>;
    private installPlayerApp;
    /**
     * Create and add multiple players to the scenario, with the same app installed
     * for each player.
     *
     * @param appsWithOptions - An app to be installed for each player
     * @returns All created player apps.
     */
    addPlayersWithSameApp(appWithOptions: AppWithOptions, amount: number): Promise<PlayerApp[]>;
    /**
     * Create and add multiple players to the scenario, with an app installed
     * for each player.
     *
     * @param appsWithOptions - An array with an app for each player.
     * @returns All created player apps.
     */
    addPlayersWithApps(appsWithOptions: AppWithOptions[]): Promise<PlayerApp[]>;
    /**
     * Register all agents of all passed in conductors to each other. This skips
     * peer discovery through gossip and thus accelerates test runs.
     *
     * @public
     */
    shareAllAgents(): Promise<void>;
    /**
     * Shut down all conductors in the scenario.
     */
    shutDown(): Promise<void>;
    /**
     * Shut down and delete all conductors in the scenario.
     */
    cleanUp(): Promise<void>;
    private ensureLocalServices;
}
/**
 * A wrapper function to create and run a scenario. A scenario is created
 * and all involved conductors are shut down and cleaned up after running.
 *
 * @param testScenario - The test to be run.
 * @param cleanUp - Whether to delete conductors after running. @defaultValue true
 *
 * @public
 */
export declare const runScenario: (testScenario: (scenario: Scenario) => Promise<void>, cleanUp?: boolean, options?: ScenarioOptions) => Promise<void>;