@povio/lightning-panda 0.0.0-stage → 0.0.17

package/dist/index.d.ts

@@ -0,0 +1,173 @@
+import { Cdp } from './cdp.js';
+import { type ScreenshotOptions, type StepLike } from './steps.js';
+import { type ScreenshotResult, type SentBaselines } from './screenshots.js';
+export * from './steps.js';
+export { Cdp, CdpError } from './cdp.js';
+export { ScreenshotMismatchError, updateMode, type ScreenshotResult } from './screenshots.js';
+export type Profile = {
+    /** Where its pages boot (and stay until a test takes one). */
+    url: string;
+    /** Written to localStorage before the app's scripts run (e.g. auth tokens). */
+    localStorage?: Record<string, string>;
+    /** Run in every document before its scripts. */
+    initScripts?: string[];
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Pages kept booted (1-8). */
+    pool?: number;
+    /** Keep pages booted ahead (default); false boots each page when a test asks. */
+    prepare?: boolean;
+    /**
+     * Steps run once on the booted page before tests get it (`serve --fork`
+     * only): every page of this profile then starts from their result.
+     */
+    setup?: StepLike[];
+    /**
+     * Starts from another profile's snapshot (`serve --fork` only): its page is
+     * forked from that profile's, and only this profile's `setup` runs on it.
+     */
+    base?: string;
+};
+export type RunResult = {
+    /** Values of `read(as)` and `evaluate(expr, as)` steps. */
+    values: Record<string, unknown>;
+    /** `matchScreenshot` steps by name. */
+    screenshots: Record<string, ScreenshotResult>;
+    /** One entry per step: what a check saw, a request it matched, settle time. */
+    results: unknown[];
+    /** Requests the page made during the run. */
+    requests: {
+        method: string;
+        url: string;
+        status: number | null;
+        error: string | null;
+        ms: number | null;
+    }[];
+    /** Time in the browser. */
+    ms: number;
+};
+export declare class RunError extends Error {
+    readonly step: number;
+    constructor(message: string, step: number);
+}
+/** One CDP connection: one browser thread, with its own page pools and screenshot baselines. */
+type Conn = {
+    cdp: Cdp;
+    open: number;
+    baselines: SentBaselines;
+    /** Opened for one page (fork mode): closed with it. */
+    own?: boolean;
+};
+export type ConnectOptions = {
+    /**
+     * CDP connections to open (default 1). Each is its own browser thread with
+     * its own pools: a test takes a page from the connection with the fewest
+     * open pages, and a connection refills its pools as soon as it has no open
+     * page, in parallel with tests on the others.
+     */
+    connections?: number;
+};
+export declare class Lightningpanda {
+    private wsUrl;
+    private conns;
+    private child?;
+    private profiles;
+    private profileMutation;
+    private turn;
+    /** `serve --fork`: one connection (a forked process) per page. */
+    private fork;
+    /** Pages taken from a pool, and pages booted on demand because none was waiting. */
+    readonly stats: {
+        prepared: number;
+        preparedBooting: number;
+        fresh: number;
+    };
+    private constructor();
+    /** Asks the server whether it forks connections (`serve --fork`). */
+    private detect;
+    /** The first connection, for browser-level commands. */
+    get cdp(): Cdp;
+    static connect(wsUrl: string, opts?: ConnectOptions): Promise<Lightningpanda>;
+    /**
+     * Starts `lightningpanda serve` on a free port and connects to it. The binary
+     * is `bin`, else `$LIGHTNINGPANDA_BIN`, else the bundled binary for this
+     * platform (or the sibling binary in a legacy release archive).
+     */
+    static launch(opts?: ConnectOptions & {
+        bin?: string;
+        args?: string[];
+    }): Promise<Lightningpanda>;
+    private updateProfiles;
+    /** Declares a kind of page tests ask for by name (`lp.page({ as: name })`). */
+    profile(name: string, profile: Profile): Promise<void>;
+    /** Releases one name, retiring shared native snapshots only after their last alias. Acquired pages remain independent. */
+    releaseProfile(name: string): Promise<void>;
+    /** Waits until every connection's pool of profile `name` is fully booted. */
+    warm(name: string, timeoutMs?: number): Promise<void>;
+    /** The connection with the fewest open pages (round-robin among equals). */
+    private pick;
+    /**
+     * A page of profile `as` (signed in, booted ahead when one is waiting),
+     * or a blank page in its own context. `route` (same-document) or `url`
+     * (a full navigation) runs as the first step of the first `run`.
+     * `initScripts` run in every document of this page before its scripts
+     * (after the profile's); a booted page already ran its document, so the
+     * page then boots fresh instead of coming from the pool.
+     */
+    page(opts?: {
+        as?: string;
+        route?: string;
+        url?: string;
+        initScripts?: string[];
+    }): Promise<Page>;
+    private openPage;
+    /** The connection URL that forks from `profileId`'s snapshot (fork mode). */
+    private forkUrl;
+    close(): void;
+}
+export declare class Page {
+    private conn;
+    readonly sessionId: string;
+    readonly targetId: string;
+    readonly browserContextId: string;
+    /** Steps the next run starts with (the page's route or navigation). */
+    prefix: StepLike[];
+    private closed;
+    constructor(conn: Conn, sessionId: string, targetId: string, browserContextId: string);
+    private get cdp();
+    /**
+     * Runs the steps in the browser as one command; throws on the first failing
+     * step (a `ScreenshotMismatchError` for a screenshot that does not match).
+     */
+    run(steps: StepLike[], opts?: {
+        timeout?: number;
+    }): Promise<RunResult>;
+    /**
+     * Expects the page (or `clip`, or `fullPage`) to match the baseline `name`:
+     * one `matchScreenshot` step. Throws `ScreenshotMismatchError` on a mismatch.
+     */
+    matchScreenshot(name: string, opts?: ScreenshotOptions): Promise<ScreenshotResult>;
+    /**
+     * Runs `source` in every document this page loads from now on, before its
+     * scripts (Playwright's `page.addInitScript`): follow it with `goto` or
+     * `reload` for the current page to see it.
+     */
+    addInitScript(source: string): Promise<void>;
+    /** Any other CDP command on this page. */
+    send<T = any>(method: string, params?: object): Promise<T>;
+    /** Closes the page and its context without waiting. */
+    close(): void;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * `expect.extend(screenshotMatchers)`, then
+ * `await expect(page).toMatchScreenshot('home', { dir })`.
+ */
+export declare const screenshotMatchers: {
+    toMatchScreenshot(page: Page, name: string, opts?: ScreenshotOptions): Promise<{
+        pass: boolean;
+        message: () => string;
+    }>;
+};