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

Toolset to manage Holochain conductors and facilitate running test scenarios

/// <reference types="node" />
/// <reference types="node" />
import { AgentPubKey, AppBundleSource, SignalCb } from "@holochain/client";
import { ChildProcessWithoutNullStreams } from "node:child_process";
import { URL } from "url";
import { AppOptions, IPlayer } from "../../types.js";
import { TryCpClient } from "../trycp-client.js";
import { TryCpConductor } from "./conductor.js";
import { TryCpConductorLogLevel } from "../types";
/**
 * @public
 */
export interface ClientsPlayersOptions {
    /**
     * An app that will be installed for each agent.
     */
    app: AppBundleSource;
    /**
     * A timeout for the web socket connection (optional).
     */
    clientTimeout?: number;
    /**
     * A list of previously generated agent pub keys (optional).
     */
    agentPubKeys?: AgentPubKey[];
    /**
     * Number of conductors per client. Defaults to 1.
     */
    numberOfConductorsPerClient?: number;
    /**
     * Number of agents per conductor. Defaults to 1.
     */
    numberOfAgentsPerConductor?: number;
    /**
     * Configuration for the conductor (optional).
     */
    partialConfig?: string;
    /**
     * A signal handler to be registered in conductors.
     */
    signalHandler?: SignalCb;
}
/**
 * A player tied to a {@link TryCpConductor}.
 *
 * @public
 */
export interface TryCpPlayer extends IPlayer {
    conductor: TryCpConductor;
}
/**
 * A TryCP client and its associated players.
 *
 * @public
 */
export interface ClientPlayers {
    client: TryCpClient;
    players: TryCpPlayer[];
}
/**
 * A test scenario abstraction with convenience functions to manage TryCP
 * clients and players (agent + conductor).
 *
 * Clients in turn help manage conductors on TryCP servers. Clients can be
 * added to a scenario to keep track of all server connections. When finishing
 * a test scenario, all conductors of all clients can be easily cleaned up and
 * the client connections closed.
 *
 * @public
 */
export declare class TryCpScenario {
    private noDpki;
    private dpkiNetworkSeed;
    network_seed: string;
    servicesProcess: ChildProcessWithoutNullStreams | undefined;
    bootstrapServerUrl: URL | undefined;
    signalingServerUrl: URL | undefined;
    clients: TryCpClient[];
    constructor();
    /**
     * Creates a TryCP client connection and add it to the scenario.
     *
     * @param serverUrl - The TryCP server URL to connect to.
     * @param timeout - An optional timeout for the web socket connection.
     * @returns The created TryCP client.
     */
    addClient(serverUrl: URL, timeout?: number): Promise<TryCpClient>;
    /**
     * Creates client connections for all passed in URLs and, depending on the
     * options, creates multiple players with apps. Adds all clients to the
     * scenario.
     *
     * If no number of agents per conductor is specified, it defaults to 1.
     *
     * @param serverUrls - The TryCP server URLs to connect to.
     * @param options - {@link ClientsPlayersOptions}
     * @returns The created TryCP clients and all conductors per client and all
     * agents' hApps per conductor.
     */
    addClientsPlayers(serverUrls: URL[], options: ClientsPlayersOptions): Promise<ClientPlayers[]>;
    /**
     * Creates and adds a single player with an installed app to the scenario,
     *
     * @param tryCpClient - The client connection to the TryCP server on which to
     * create the player.
     * @param appBundleSource - The bundle or path of the app.
     * @param options - {@link AppOptions} like agent pub key etc.
     * @returns The created player instance.
     */
    addPlayerWithApp(tryCpClient: TryCpClient, appBundleSource: AppBundleSource, options?: AppOptions & {
        logLevel?: TryCpConductorLogLevel;
    }): Promise<TryCpPlayer>;
    /**
     * Creates and adds multiple players with an installed app to the scenario.
     *
     * @param tryCpClient - The client connection to the TryCP server on which to
     * create the player.
     * @param playersApps - An array with an app for each player.
     * @returns An array of the added players.
     */
    addPlayersWithApps(tryCpClient: TryCpClient, playersApps: Array<{
        appBundleSource: AppBundleSource;
        options?: AppOptions;
    }>): Promise<TryCpPlayer[]>;
    /**
     * Registers all agents of all passed in conductors to each other. This skips
     * peer discovery through gossip and thus accelerates test runs.
     */
    shareAllAgents(): Promise<void>;
    /**
     * Shut down all conductors of all clients in the scenario.
     */
    shutDown(): Promise<void>;
    /**
     * Shut down and delete all conductors and close all client connections in
     * the scenario.
     */
    cleanUp(): Promise<void>;
}