@itmetsam/samurai-framework 0.10.0 → 0.12.0

package/dist/browser/launch-firefox.js

@@ -0,0 +1,66 @@
+import { spawn } from "node:child_process";
+import logger from "../logger/index.js";
+import { BiDiConnector } from "../transport/bidi-connection.js";
+import { browserLaunchEnv, browserLaunchFlag, defaultLaunchOptions, } from "./launch-flags.js";
+import { abandonLaunch, startSession } from "./session.js";
+// Firefox logs "WebDriver BiDi listening on ws://<host>:<port>" without the endpoint path
+const FIREFOX_WS_PATH = "/session";
+const FIREFOX_WS_REGEX = /ws:\/\/\d{1,3}(?:\.\d{1,3}){3}:\d+/g;
+const PORT_IN_USE = /!!!\scould\snot\sstart\sserver\son\sport\s\d+/;
+/**
+ * Starts Firefox, waits for it to announce its BiDi endpoint, connects and opens the BiDi session.
+ * Rejects with an Error when the process exits first or the handshake fails, with the abort reason when aborted,
+ * and with a message string when the debugging port is taken. A failed launch stops what it started.
+ */
+export function launchFirefox(launch) {
+    const { executablePath, label, launchOptions, commandTimeout, signal } = launch;
+    logger.verbose("Trying to spawn firefox process");
+    const proc = spawn(executablePath, browserLaunchFlag("firefox", launchOptions), { env: { ...process.env, ...browserLaunchEnv("firefox") } });
+    return new Promise((resolve, reject) => {
+        const onUnexpectedClose = (code) => reject(new Error(`Browser process exited unexpectedly with code ${code}`));
+        proc.on("close", onUnexpectedClose);
+        const onAbort = () => {
+            logger.verbose("Launch of firefox aborted, killing process");
+            proc.kill();
+            reject(signal?.reason);
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const settled = () => {
+            proc.off("close", onUnexpectedClose);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        proc.stdout.on("data", (data) => {
+            logger.debug(`firefox stdout: ${data}`);
+            if (PORT_IN_USE.test(String(data))) {
+                proc.kill();
+                reject(`PORT ${launchOptions.port ?? defaultLaunchOptions("firefox").port} is already in use!`);
+            }
+        });
+        proc.stderr.on("data", async (data) => {
+            logger.debug(`firefox stderr: ${data}`);
+            const urlMatch = String(data).match(FIREFOX_WS_REGEX);
+            logger.debug("Browser announced its endpoint", { urlMatch });
+            if (!urlMatch || urlMatch.length === 0)
+                return;
+            // Killing the process mid-handshake rejects pending BiDi calls; surface that via reject
+            // instead of an unhandled rejection from this async listener
+            let connector;
+            try {
+                const url = urlMatch[0] + FIREFOX_WS_PATH;
+                logger.verbose("Websocket URL match: %s", url);
+                connector = await BiDiConnector.connect(url, { commandTimeout });
+                const status = await connector.send("session.status", {});
+                logger.verbose("Session status", status);
+                await startSession(connector, label, commandTimeout);
+                logger.verbose("Session started successfully");
+                settled();
+                resolve({ proc, connector });
+            }
+            catch (err) {
+                settled();
+                abandonLaunch(proc, connector);
+                reject(err);
+            }
+        });
+    });
+}

package/dist/browser/launch-flags.d.ts

@@ -0,0 +1,18 @@
+import type { SupportedBrowser } from "../types/browser.js";
+export interface BrowserLaunchOptions {
+    /** Which port to use for the WebDeveloper tools */
+    port: number;
+    /** The browser profile folder: user.js goes in it for Firefox, Chrome's user data for Chrome */
+    profileDir: string;
+    /** Start the browser in headless mode or in UI mode */
+    headless: boolean;
+}
+/** The profile folder of a worker: worker 0 keeps the browser's own folder, worker N gets `<browser>-wN` beside it */
+export declare const workerProfileDir: (browserName: SupportedBrowser, workerIndex: number) => string;
+/** Read when a browser launches, since the profile folder depends on the active project */
+export declare const defaultLaunchOptions: (browserName: SupportedBrowser) => BrowserLaunchOptions;
+export declare const browserLaunchFlag: (browserName: SupportedBrowser, launchOptions: Partial<BrowserLaunchOptions>) => string[];
+/** Env added to a browser's process */
+export declare const browserLaunchEnv: (browserName: SupportedBrowser, appDataPath?: string) => Record<string, string>;
+/** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
+export declare function ensureBrowserProfile(browserName: SupportedBrowser, profilePath?: string | undefined): void;

package/dist/browser/launch-flags.js

@@ -0,0 +1,100 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { browsersDir } from "../config/config.js";
+import logger from "../logger/index.js";
+const browserProfilePath = (browserName) => path.join(browsersDir(), "profiles", browserName, "user.js");
+const baseBrowserLaunchFlags = {
+    // Chrome is started by its chromedriver: see chrome-launch.ts
+    chrome: [],
+    firefox: ["--no-sandbox", "--no-remote"],
+};
+/** The profile folder of a worker: worker 0 keeps the browser's own folder, worker N gets `<browser>-wN` beside it */
+export const workerProfileDir = (browserName, workerIndex) => workerIndex === 0
+    ? path.dirname(browserProfilePath(browserName))
+    : path.join(browsersDir(), "profiles", `${browserName}-w${workerIndex}`);
+/** Read when a browser launches, since the profile folder depends on the active project */
+export const defaultLaunchOptions = (browserName) => ({
+    port: 9222,
+    profileDir: path.dirname(browserProfilePath(browserName)),
+    headless: true,
+});
+export const browserLaunchFlag = (browserName, launchOptions) => {
+    const defLaunchOpts = defaultLaunchOptions(browserName);
+    const port = launchOptions.port || defLaunchOpts.port;
+    const profileDir = launchOptions.profileDir || defLaunchOpts.profileDir;
+    const headless = launchOptions.headless ?? defLaunchOpts.headless;
+    const baseLaunchFlags = [...baseBrowserLaunchFlags[browserName]];
+    if (headless) {
+        baseLaunchFlags.push("--headless");
+    }
+    baseLaunchFlags.push(`--remote-debugging-port=${port}`);
+    switch (browserName) {
+        case "chrome":
+            break;
+        case "firefox":
+            baseLaunchFlags.push("--profile", profileDir);
+            // The home page (about:home) is privileged: BiDi refuses commands such as setViewport on it
+            baseLaunchFlags.push("about:blank");
+            break;
+    }
+    logger.verbose("Launch flags for browser %s: ", browserName, {
+        baseLaunchFlags,
+    });
+    return baseLaunchFlags;
+};
+// On macOS a spawned browser is attributed to the terminal, which is denied access to
+// ~/Library/Application Support/Firefox (profiles.ini). Point Firefox at a local app data dir instead.
+const browserAppDataPath = (browserName) => path.join(browsersDir(), "app-data", browserName);
+/** Env added to a browser's process */
+export const browserLaunchEnv = (browserName, appDataPath = browserAppDataPath(browserName)) => {
+    mkdirSync(appDataPath, { recursive: true });
+    logger.debug("Using app data dir for %s: %s", browserName, appDataPath);
+    switch (browserName) {
+        case "chrome":
+            return {};
+        case "firefox":
+            // The project profile may have been opened by a newer Firefox (the system one, before 0.6);
+            // without this Firefox refuses to start on it
+            return { MOZ_APP_DATA: appDataPath, MOZ_ALLOW_DOWNGRADE: "1" };
+    }
+};
+const browserProfiles = {
+    // Chrome needs no prefs file; its profile folder is created at launch
+    chrome: "",
+    firefox: `
+    user_pref("devtools.debugger.remote-enabled", true);
+    user_pref("devtools.debugger.prompt-connection", false);
+    user_pref("devtools.chrome.enabled", true);
+    // The home page (about:home) is privileged: BiDi refuses commands such as setViewport on it
+    user_pref("browser.startup.page", 0);
+    user_pref("browser.startup.homepage", "about:blank");
+    user_pref("browser.newtabpage.enabled", false);
+  `,
+};
+/** Writes the browser's user.js unless it already holds the current prefs; an outdated one is replaced */
+export function ensureBrowserProfile(browserName, profilePath = browserProfilePath(browserName)) {
+    logger.verbose("Checking browser profile for: %s", browserName);
+    if (!profilePath) {
+        logger.verbose("No browser profile path declared, skipping...");
+        return;
+    }
+    if (existsSync(profilePath)) {
+        if (readFileSync(profilePath, "utf8") === browserProfiles[browserName]) {
+            logger.verbose("Browser profile is up to date at: %s", profilePath);
+            return;
+        }
+        logger.verbose("Browser profile at %s is outdated, rewriting it", profilePath);
+    }
+    else {
+        logger.verbose("No browser profile created yet for %s", browserName);
+    }
+    createBrowserProfile(browserName, profilePath);
+}
+function createBrowserProfile(browserName, profilePath) {
+    logger.verbose("Creating browser profile for %s at %s", browserName, profilePath);
+    mkdirSync(path.dirname(profilePath), { recursive: true });
+    writeFileSync(profilePath, browserProfiles[browserName], {
+        encoding: "utf8",
+    });
+    logger.verbose("Browser profile created");
+}

package/dist/browser/lazy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Something started on first use and shared by everyone who asks: concurrent callers get the same promise, a failed
+ * start is forgotten so the next call tries again, and the finished value can be read without waiting (`peek`).
+ */
+export declare class Lazy<T> {
+    private promise;
+    private value;
+    /** Whether a start was made and not forgotten since (it may still be running or have failed and been kept) */
+    get started(): boolean;
+    /**
+     * The shared start, made by `factory` on the first call. `keepFailure` says which failures stay (every later call
+     * gets the same rejection) instead of being forgotten.
+     */
+    get(factory: () => Promise<T>, keepFailure?: (err: unknown) => boolean): Promise<T>;
+    /** The value once the start finished, else undefined */
+    peek(): T | undefined;
+    /** Forgets the start; the next `get` starts again */
+    reset(): void;
+    /** Forgets the start and hands back its promise, for the caller to dispose; undefined when nothing was started */
+    take(): Promise<T> | undefined;
+}

package/dist/browser/lazy.js

@@ -0,0 +1,44 @@
+/**
+ * Something started on first use and shared by everyone who asks: concurrent callers get the same promise, a failed
+ * start is forgotten so the next call tries again, and the finished value can be read without waiting (`peek`).
+ */
+export class Lazy {
+    /** Whether a start was made and not forgotten since (it may still be running or have failed and been kept) */
+    get started() {
+        return this.promise !== undefined;
+    }
+    /**
+     * The shared start, made by `factory` on the first call. `keepFailure` says which failures stay (every later call
+     * gets the same rejection) instead of being forgotten.
+     */
+    get(factory, keepFailure = () => false) {
+        if (this.promise)
+            return this.promise;
+        const started = (async () => factory())().then((value) => {
+            if (this.promise === started)
+                this.value = value;
+            return value;
+        }, (err) => {
+            if (this.promise === started && !keepFailure(err))
+                this.reset();
+            throw err;
+        });
+        this.promise = started;
+        return started;
+    }
+    /** The value once the start finished, else undefined */
+    peek() {
+        return this.value;
+    }
+    /** Forgets the start; the next `get` starts again */
+    reset() {
+        this.promise = undefined;
+        this.value = undefined;
+    }
+    /** Forgets the start and hands back its promise, for the caller to dispose; undefined when nothing was started */
+    take() {
+        const promise = this.promise;
+        this.reset();
+        return promise;
+    }
+}

package/dist/browser/page-events.d.ts

@@ -0,0 +1,44 @@
+import type EventEmitter from "node:events";
+import type { FailedRequest, NetworkRequest } from "../network/network-tracker.js";
+import type { Response } from "../network/response.js";
+import type { ConsoleMessage, PageError } from "./page-logs.js";
+import type { Dialog } from "./dialog.js";
+import type { Download } from "./download.js";
+import type { FileChooser } from "./file-chooser.js";
+export interface NetworkEvents {
+    request: [NetworkRequest];
+    response: [Response];
+    requestfailed: [FailedRequest];
+}
+/** Everything `page.on` can listen for */
+export interface PageEvents extends NetworkEvents {
+    download: [Download];
+    filechooser: [FileChooser];
+    dialog: [Dialog];
+    console: [ConsoleMessage];
+    pageerror: [PageError];
+}
+export type PageEventName = keyof PageEvents;
+/** Events `page.waitForEvent` can wait for */
+export type WaitableEventName = "download" | "filechooser" | "request" | "response";
+/** What the `waitFor…` calls of a page take */
+export interface WaitOptions {
+    /** Time (ms) to wait. @default config `navigation.timeout`, then 30000 */
+    timeout?: number;
+    /** Runs once the wait is set up; what it causes cannot be missed */
+    trigger?: () => Promise<unknown>;
+}
+export interface WaitForEventOptions<T> extends WaitOptions {
+    /** Only an event this accepts counts */
+    predicate?: (item: T) => boolean;
+}
+/** What has to be switched on in the browser before an event can arrive */
+export type EventSource = "dialogs" | "downloads" | "filechoosers" | "logs" | "network" | "bodies";
+/** The parts of the page that must be listening for `event` to happen (a `response` also needs the bodies) */
+export declare function sourcesFor(event: PageEventName): EventSource[];
+/**
+ * Resolves with the first `event` that `matches` accepts. Listens before `options.trigger` runs, so what the trigger
+ * causes cannot be missed; a trigger that throws rejects the wait with its error. `onTimeout` builds the error for a
+ * wait that ran out after `timeout` ms.
+ */
+export declare function waitForPageEvent<E extends PageEventName>(emitter: EventEmitter, event: E, matches: (item: PageEvents[E][0]) => boolean, options: Pick<WaitOptions, "trigger">, timeout: number, onTimeout: (timeout: number) => Error): Promise<PageEvents[E][0]>;

package/dist/browser/page-events.js

@@ -0,0 +1,58 @@
+/** The parts of the page that must be listening for `event` to happen (a `response` also needs the bodies) */
+export function sourcesFor(event) {
+    switch (event) {
+        case "dialog":
+            return ["dialogs"];
+        case "download":
+            return ["downloads"];
+        case "filechooser":
+            return ["filechoosers"];
+        case "console":
+        case "pageerror":
+            return ["logs"];
+        case "response":
+            return ["network", "bodies"];
+        default:
+            return ["network"];
+    }
+}
+/**
+ * Resolves with the first `event` that `matches` accepts. Listens before `options.trigger` runs, so what the trigger
+ * causes cannot be missed; a trigger that throws rejects the wait with its error. `onTimeout` builds the error for a
+ * wait that ran out after `timeout` ms.
+ */
+export function waitForPageEvent(emitter, event, matches, options, timeout, onTimeout) {
+    return new Promise((resolve, reject) => {
+        const done = () => {
+            clearTimeout(timer);
+            emitter.off(event, listener);
+        };
+        const listener = (item) => {
+            try {
+                if (!matches(item))
+                    return;
+            }
+            catch (err) {
+                done();
+                reject(err);
+                return;
+            }
+            done();
+            resolve(item);
+        };
+        const timer = setTimeout(() => {
+            done();
+            reject(onTimeout(timeout));
+        }, timeout);
+        emitter.on(event, listener);
+        const { trigger } = options;
+        if (trigger) {
+            Promise.resolve()
+                .then(trigger)
+                .catch((err) => {
+                done();
+                reject(err);
+            });
+        }
+    });
+}

package/dist/browser/page-logs.js

@@ -1,5 +1,5 @@
 import EventEmitter from "node:events";
-import logger from "../logger/index.js";
+import { emitSafely } from "./emit.js";
 import { fromRemoteValue } from "../script/serialize.js";
 /** How many entries a page keeps before the oldest are dropped */
 const DEFAULT_MAX_ENTRIES = 1000;
@@ -157,13 +157,6 @@ export class PageLogs {
     }
     /** A listener that throws must not stop the recording or the other listeners */
     emit(event, ...args) {
-        for (const listener of this.events.rawListeners(event)) {
-            try {
-                listener(...args);
-            }
-            catch (err) {
-                logger.error("A %s listener threw", event, { err });
-            }
-        }
+        emitSafely(this.events, event, args);
     }
 }

package/dist/browser/page-navigation.d.ts

@@ -0,0 +1,58 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { DocumentWatcher } from "./document-watcher.js";
+import type { PageConfig, ReadinessState } from "./page-settings.js";
+export type LoadState = "load" | "domcontentloaded" | "networkidle";
+export interface NavigateOptions {
+    /** When navigateTo resolves. @default config `navigation.waitUntil`, then "complete" */
+    wait?: ReadinessState;
+    /** Time (ms) the navigation may take. @default config `navigation.timeout`, then 30000 */
+    timeout?: number;
+    /** Scheme added to a URL without one. @default "https" */
+    protocol?: "http" | "https";
+}
+/** What a navigation answers with: its id (null when the browser gave none) and the URL it ended on */
+export type NavigationResult = {
+    navigation: string | null;
+    url: string;
+};
+/** What `PageNavigation` takes from the page it belongs to */
+export interface NavigationDeps {
+    config: PageConfig;
+    documents: DocumentWatcher;
+    /** Throws when the page is closed */
+    assertOpen(): void;
+    /** The URL of the page now, for the text of a failed navigation */
+    url(): Promise<string>;
+    /** Waits for a quiet network, for the "networkidle" load state */
+    waitForNetworkIdle(options: {
+        timeout: number;
+    }): Promise<void>;
+}
+/** Navigating one page: `goto`, `navigateTo`, `reload` and the wait for a load state */
+export declare class PageNavigation {
+    private connector;
+    private contextId;
+    private deps;
+    /** The navigation started by the last navigateTo; failures of it fail a wait */
+    private lastNavigation;
+    /** Base for relative `goto` URLs; falls back to the active run's baseURL */
+    private baseURL;
+    constructor(connector: BiDiConnector, contextId: string, deps: NavigationDeps);
+    /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
+    setBaseURL(url: string | undefined): void;
+    goto(url: string, options?: NavigateOptions): Promise<NavigationResult>;
+    navigateTo(url: string, options?: NavigateOptions | ReadinessState, protocol?: "http" | "https"): Promise<NavigationResult>;
+    reload(options?: {
+        wait?: ReadinessState;
+        timeout?: number;
+        ignoreCache?: boolean;
+    }): Promise<NavigationResult>;
+    waitForLoadState(state?: LoadState, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Runs a navigation command and settles what waiting for it means: failures become NavigationErrors, and a
+     * navigation that did not wait for the load is watched so `waitForLoadState` can tell it from the old page.
+     */
+    private navigation;
+}

package/dist/browser/page-navigation.js

@@ -0,0 +1,108 @@
+import { peekRunSettings } from "../config/run-settings.js";
+import { BiDiError } from "../transport/bidi-error.js";
+import { UnsupportedOperationError } from "../transport/unsupported.js";
+import { WaitTimeoutError } from "../wait/wait-until.js";
+import { LoadStateTimeoutError, NavigationError } from "./navigation-error.js";
+/** Navigating one page: `goto`, `navigateTo`, `reload` and the wait for a load state */
+export class PageNavigation {
+    constructor(connector, contextId, deps) {
+        this.connector = connector;
+        this.contextId = contextId;
+        this.deps = deps;
+    }
+    /** Sets the base that relative `goto` URLs resolve against; `undefined` falls back to the run's baseURL */
+    setBaseURL(url) {
+        this.baseURL = url;
+    }
+    async goto(url, options) {
+        if (!/^\.{0,2}\//.test(url))
+            return this.navigateTo(url, options);
+        const base = this.baseURL ?? peekRunSettings()?.baseURL;
+        if (!base) {
+            throw new Error(`goto(): "${url}" needs a baseURL; set one in samurai.config.ts or the environment`);
+        }
+        return this.navigateTo(new URL(url, base).href, options);
+    }
+    async navigateTo(url, options, protocol) {
+        const given = typeof options === "string" ? { wait: options } : (options ?? {});
+        const wait = await this.deps.config.navigationWait(given.wait);
+        const timeout = await this.deps.config.navigationTimeout(given.timeout);
+        // A scheme is letters followed by ":" not directly followed by a digit, so "localhost:3000" is a host
+        const hasScheme = /^[a-z][a-z\d+.-]*:(?!\d)/i.test(url);
+        const parsedURL = hasScheme
+            ? url
+            : `${given.protocol ?? protocol ?? "https"}://${url}`;
+        this.deps.assertOpen();
+        return this.navigation("navigateTo", async () => parsedURL, wait, timeout, async (sendOptions) => {
+            const result = await this.connector.send("browsingContext.navigate", { context: this.contextId, url: parsedURL, wait }, sendOptions);
+            return {
+                navigation: result.navigation ?? null,
+                url: result.url ?? parsedURL,
+            };
+        });
+    }
+    async reload(options = {}) {
+        this.deps.assertOpen();
+        const wait = await this.deps.config.navigationWait(options.wait);
+        const timeout = await this.deps.config.navigationTimeout(options.timeout);
+        return this.navigation("reload", () => this.deps.url().catch(() => "the page"), wait, timeout, async (sendOptions) => {
+            try {
+                const result = await this.connector.send("browsingContext.reload", {
+                    context: this.contextId,
+                    wait,
+                    ...(options.ignoreCache && { ignoreCache: true }),
+                }, sendOptions);
+                return { navigation: result.navigation ?? null, url: result.url };
+            }
+            catch (err) {
+                if (options.ignoreCache &&
+                    err instanceof BiDiError &&
+                    err.code === "unsupported operation") {
+                    throw new UnsupportedOperationError("reload(): ignoreCache is not supported by the browser");
+                }
+                throw err;
+            }
+        });
+    }
+    async waitForLoadState(state = "load", options = {}) {
+        this.deps.assertOpen();
+        const timeout = await this.deps.config.navigationTimeout(options.timeout);
+        try {
+            await this.deps.documents.waitForState(state === "domcontentloaded" ? "domcontentloaded" : "load", timeout, this.lastNavigation);
+        }
+        catch (err) {
+            if (err instanceof WaitTimeoutError)
+                throw new LoadStateTimeoutError(state, timeout);
+            throw err;
+        }
+        if (state === "networkidle")
+            await this.deps.waitForNetworkIdle({ timeout });
+    }
+    /**
+     * Runs a navigation command and settles what waiting for it means: failures become NavigationErrors, and a
+     * navigation that did not wait for the load is watched so `waitForLoadState` can tell it from the old page.
+     */
+    async navigation(operation, describe, wait, timeout, send) {
+        // A navigation that does not wait for the load needs watching, or waitForLoadState cannot tell it from the old page
+        if (wait !== "complete")
+            await this.deps.documents.watch();
+        try {
+            const result = await send({ timeout });
+            this.lastNavigation = result.navigation ?? undefined;
+            if (result.navigation && wait !== "complete") {
+                // Tracked from now on: the document still showing is the old one until this navigation commits
+                const progress = this.deps.documents.progressOf(result.navigation);
+                if (wait === "interactive")
+                    progress.domContentLoaded = true;
+            }
+            return result;
+        }
+        catch (err) {
+            if (err instanceof BiDiError) {
+                const reason = err.code === "timeout" ? `timeout after ${timeout}ms` : err.message;
+                throw new NavigationError(await describe(), reason, err.code, operation);
+            }
+            throw err;
+        }
+    }
+}

package/dist/browser/page-network.d.ts

@@ -0,0 +1,69 @@
+import type EventEmitter from "node:events";
+import { NetworkTracker } from "../network/network-tracker.js";
+import type { NetworkRequest } from "../network/network-tracker.js";
+import { type NetworkMatch } from "../network/network-wait.js";
+import { Response } from "../network/response.js";
+import { type RouteHandler } from "../network/router.js";
+import type { UrlPattern } from "../network/url-match.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { BrowsingContext } from "../types/bidi-modules/browsing-context.js";
+import type { TreeSource } from "./dialog-handling.js";
+import type { PageEventName, PageEvents, WaitOptions } from "./page-events.js";
+import type { PageConfig } from "./page-settings.js";
+/** What `PageNetwork` takes from the page around it */
+export interface PageNetworkDeps {
+    config: PageConfig;
+    tree: TreeSource;
+    /** Where `request`, `response` and `requestfailed` are emitted */
+    emitter: EventEmitter;
+    /** Resolves with the first event of a kind that `matches` accepts (the page's `waitForPageEvent`) */
+    waitForEvent: <E extends PageEventName>(event: E, matches: (item: PageEvents[E][0]) => boolean, options: WaitOptions, onTimeout: (timeout: number) => Error) => Promise<PageEvents[E][0]>;
+}
+/**
+ * Everything a page does with its network: request tracking and idle waits, response bodies, waiting for a
+ * request or response, the HTTP cache switch and the routes (interception).
+ */
+export declare class PageNetwork {
+    private connector;
+    private contextId;
+    private deps;
+    private lazyTracker;
+    private lazyCollector;
+    private lazyRouter;
+    private responses;
+    constructor(connector: BiDiConnector, contextId: BrowsingContext, deps: PageNetworkDeps);
+    /** The network tracker, created on first use. Rejects with NetworkTrackingDisabledError when config turned tracking off */
+    tracker(): Promise<NetworkTracker>;
+    /** Starts following requests now; does nothing when config `network.track` is false */
+    startTracking(): Promise<void>;
+    /** Waits until no request has been in flight for `idleTime` ms (default config `network.idleTime`, then 500) */
+    waitForIdle(options?: {
+        idleTime?: number;
+        timeout?: number;
+    }): Promise<void>;
+    /** Starts keeping response bodies, which is what makes `response.body()` possible */
+    startBodyCollection(): Promise<void>;
+    private openCollector;
+    /** One Response per network response, whoever asks, so a body is read from the browser once */
+    private responseFor;
+    private loadBody;
+    /** Resolves with the next response whose URL matches (a pattern, see `route`) or that the function accepts */
+    waitForResponse(match: NetworkMatch<Response>, options?: WaitOptions): Promise<Response>;
+    /** Like `waitForResponse`, for requests */
+    waitForRequest(match: NetworkMatch<NetworkRequest>, options?: WaitOptions): Promise<NetworkRequest>;
+    private waitForNetworkEvent;
+    /** Turns the browser's HTTP cache off (`true`) or back on for this page: every request then goes to the server */
+    setCacheDisabled(disabled: boolean): Promise<void>;
+    private router;
+    /** Sends requests whose URL matches to `handler` (see `Page.route`) */
+    route(url: UrlPattern, handler: RouteHandler): Promise<void>;
+    /** Removes the routes for `url` (only the one with `handler`, when given) */
+    unroute(url: UrlPattern, handler?: RouteHandler): Promise<void>;
+    unrouteAll(): Promise<void>;
+    /** Errors thrown by route handlers so far */
+    routeErrors(): readonly Error[];
+    /** The first half of releasing the network: the tracker goes before the tree it reads */
+    disposeTracker(): Promise<void>;
+    /** The second half: the router, then the body collector */
+    disposeRest(): (Promise<void> | undefined)[];
+}