@itmetsam/samurai-framework 0.1.0 → 0.2.0

package/dist/browser/download.js

@@ -0,0 +1,137 @@
+import EventEmitter from "node:events";
+import logger from "../logger/index.js";
+import { WaitTimeoutError } from "../wait/wait-until.js";
+/** A download did not complete */
+export class DownloadError extends Error {
+    constructor(url, reason) {
+        super(`Download of ${url} failed: ${reason}`);
+        this.name = "DownloadError";
+        this.url = url;
+        this.reason = reason;
+    }
+}
+/** A download did not finish in time */
+export class DownloadTimeoutError extends WaitTimeoutError {
+    constructor(url, timeout) {
+        super(timeout, undefined);
+        this.name = "DownloadTimeoutError";
+        this.message = `Download of ${url} did not finish within ${timeout}ms`;
+    }
+}
+/** A file the page started to download */
+export class Download {
+    constructor(address, filename, defaultTimeout) {
+        this.address = address;
+        this.filename = filename;
+        this.defaultTimeout = defaultTimeout;
+        this.outcome = new Promise((resolve) => (this.settle = resolve));
+    }
+    url() {
+        return this.address;
+    }
+    /** The name the server (or the link) suggested */
+    suggestedFilename() {
+        return this.filename;
+    }
+    /**
+     * Waits until the download finished and returns where the browser saved it. Rejects with DownloadError when it was
+     * cancelled, and with DownloadTimeoutError after `timeout` ms (default: the navigation timeout).
+     */
+    async path(options = {}) {
+        const timeout = options.timeout ?? this.defaultTimeout;
+        let timer;
+        const late = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new DownloadTimeoutError(this.address, timeout)), timeout);
+        });
+        try {
+            const outcome = await Promise.race([this.outcome, late]);
+            if (outcome.status === "complete")
+                return outcome.path;
+            throw new DownloadError(this.address, outcome.status === "closed" ? "page closed" : "canceled");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** Waits for the end of the download: null when it completed, otherwise why it did not ("canceled") */
+    async failure() {
+        const outcome = await this.outcome;
+        if (outcome.status === "complete")
+            return null;
+        return outcome.status === "closed" ? "page closed" : "canceled";
+    }
+    /** @internal */
+    finish(outcome) {
+        this.settle(outcome);
+    }
+}
+/** Follows the downloads of one page (frames included) */
+export class DownloadTracker {
+    constructor(connector, tree, contextId, timeout) {
+        this.connector = connector;
+        this.tree = tree;
+        this.contextId = contextId;
+        this.timeout = timeout;
+        this.events = new EventEmitter();
+        this.active = new Map();
+        this.disposed = false;
+        this.onBegin = (params) => {
+            if (!this.tree.isWithin(params.context, this.contextId))
+                return;
+            const download = new Download(params.url, params.suggestedFilename, this.timeout);
+            this.active.set(params.navigation, download);
+            for (const listener of this.events.rawListeners("download")) {
+                try {
+                    listener(download);
+                }
+                catch (err) {
+                    logger.error("A download listener threw", { err });
+                }
+            }
+        };
+        this.onEnd = (params) => {
+            const download = this.active.get(params.navigation);
+            if (!download)
+                return;
+            this.active.delete(params.navigation);
+            download.finish(params.status === "complete" ? { status: "complete", path: params.filepath } : { status: "canceled" });
+        };
+    }
+    static async start(connector, tree, contextId, options) {
+        const tracker = new DownloadTracker(connector, tree, contextId, options.timeout);
+        connector.onEvent("browsingContext.downloadWillBegin", tracker.onBegin);
+        connector.onEvent("browsingContext.downloadEnd", tracker.onEnd);
+        try {
+            tracker.subscription = await connector.subscribe([
+                "browsingContext.downloadWillBegin",
+                "browsingContext.downloadEnd",
+            ]);
+        }
+        catch (err) {
+            tracker.removeListeners();
+            throw err;
+        }
+        return tracker;
+    }
+    on(event, listener) {
+        this.events.on(event, listener);
+    }
+    off(event, listener) {
+        this.events.off(event, listener);
+    }
+    /** Stops tracking; downloads still going on reject with "page closed". Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.removeListeners();
+        for (const download of this.active.values())
+            download.finish({ status: "closed" });
+        this.active.clear();
+        await this.subscription?.unsubscribe();
+    }
+    removeListeners() {
+        this.connector.offEvent("browsingContext.downloadWillBegin", this.onBegin);
+        this.connector.offEvent("browsingContext.downloadEnd", this.onEnd);
+    }
+}

package/dist/browser/downloads-dir.d.ts

@@ -0,0 +1,8 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+/**
+ * Makes downloads land in a folder of their own, so a test knows where to look and runs do not mix: a new folder
+ * below `baseDir` is created and the browser told to save there. Returns it, or undefined when the browser cannot be told.
+ */
+export declare function prepareDownloadsDir(connector: BiDiConnector, baseDir: string): Promise<string | undefined>;
+/** Removes `dir` when nothing was downloaded into it. Never throws */
+export declare function removeIfEmpty(dir: string | undefined): void;

package/dist/browser/downloads-dir.js

@@ -0,0 +1,38 @@
+import { mkdirSync, rmdirSync } from "node:fs";
+import path from "node:path";
+import logger from "../logger/index.js";
+import { BiDiError } from "../transport/bidi-error.js";
+let counter = 0;
+/**
+ * Makes downloads land in a folder of their own, so a test knows where to look and runs do not mix: a new folder
+ * below `baseDir` is created and the browser told to save there. Returns it, or undefined when the browser cannot be told.
+ */
+export async function prepareDownloadsDir(connector, baseDir) {
+    const dir = path.join(path.resolve(baseDir), `dl-${Date.now().toString(36)}-${process.pid}-${counter++}`);
+    mkdirSync(dir, { recursive: true });
+    try {
+        await connector.send("browser.setDownloadBehavior", {
+            downloadBehavior: { type: "allowed", destinationFolder: dir },
+        });
+    }
+    catch (err) {
+        removeIfEmpty(dir);
+        if (err instanceof BiDiError && (err.code === "unknown command" || err.code === "unsupported operation")) {
+            logger.warn("The browser cannot be told where to save downloads; they go to its own folder");
+            return undefined;
+        }
+        throw err;
+    }
+    return dir;
+}
+/** Removes `dir` when nothing was downloaded into it. Never throws */
+export function removeIfEmpty(dir) {
+    if (!dir)
+        return;
+    try {
+        rmdirSync(dir);
+    }
+    catch {
+        // Not empty, or already gone: leave it
+    }
+}

package/dist/browser/emulation.d.ts

@@ -0,0 +1,61 @@
+import { UnsupportedOperationError } from "../locator/selector-errors.js";
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+declare const ORIENTATIONS: readonly ["portrait-primary", "portrait-secondary", "landscape-primary", "landscape-secondary"];
+type OrientationType = (typeof ORIENTATIONS)[number];
+/**
+ * What to pretend about the browser. `undefined` leaves an option as it is, `null` puts the real value back.
+ * Which options a browser supports differs: an unsupported one throws UnsupportedOperationError.
+ */
+export interface EmulationOptions {
+    /** A BCP 47 tag, e.g. "nl-NL": `navigator.language`, `Intl` formatting */
+    locale?: string | null;
+    /** An IANA timezone, e.g. "Europe/Amsterdam" */
+    timezone?: string | null;
+    userAgent?: string | null;
+    /** Needs the geolocation permission: see `page.grantPermission("geolocation")` */
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    } | null;
+    /** `true`: no network (`navigator.onLine` is false and requests fail); `false` or `null`: back online */
+    offline?: boolean | null;
+    /** "portrait" and "landscape" mean the primary orientation of that kind */
+    orientation?: "portrait" | "landscape" | OrientationType | null;
+    /** The size `screen.width` and `screen.height` report */
+    screen?: {
+        width: number;
+        height: number;
+    } | null;
+    /** How many touch points `navigator.maxTouchPoints` reports */
+    touch?: number | null;
+    /** `false` turns JavaScript off; `true` or `null` on again */
+    javaScriptEnabled?: boolean | null;
+}
+export type EmulationTarget = {
+    contexts: string[];
+} | {
+    userContexts: string[];
+};
+/** A part of the options could not be applied; what was applied before it stays applied */
+export declare class EmulationError extends Error {
+    /** The options that were applied before the failure, in the order they were applied */
+    readonly applied: string[];
+    readonly failed: string;
+    readonly cause: unknown;
+    constructor(failed: string, applied: string[], cause: unknown);
+}
+/** The browser does not implement an emulation command */
+export declare class EmulationUnsupportedError extends UnsupportedOperationError {
+    readonly option: string;
+    readonly applied: string[];
+    constructor(option: string, applied: string[]);
+}
+/** Throws RangeError when a value is invalid, without sending anything */
+export declare function validateEmulation(options: EmulationOptions): void;
+/**
+ * Applies the options to `target`, one command after the other. Nothing is rolled back when one fails:
+ * the error says what was applied.
+ */
+export declare function applyEmulation(connector: BiDiConnector, target: EmulationTarget, options: EmulationOptions): Promise<void>;
+export {};

package/dist/browser/emulation.js

@@ -0,0 +1,144 @@
+import { UnsupportedOperationError } from "../locator/selector-errors.js";
+import { BiDiError } from "../transport/bidi-error.js";
+const ORIENTATIONS = [
+    "portrait-primary",
+    "portrait-secondary",
+    "landscape-primary",
+    "landscape-secondary",
+];
+/** A part of the options could not be applied; what was applied before it stays applied */
+export class EmulationError extends Error {
+    constructor(failed, applied, cause) {
+        const detail = cause instanceof Error ? cause.message : String(cause);
+        super(`emulate(): ${failed} failed${applied.length ? ` after applying ${applied.join(", ")}` : ""}: ${detail}`);
+        this.name = "EmulationError";
+        this.failed = failed;
+        this.applied = applied;
+        this.cause = cause;
+    }
+}
+/** The browser does not implement an emulation command */
+export class EmulationUnsupportedError extends UnsupportedOperationError {
+    constructor(option, applied) {
+        super(`emulate({ ${option} }) is not supported by the browser`);
+        this.name = "EmulationUnsupportedError";
+        this.option = option;
+        this.applied = applied;
+    }
+}
+const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
+/** Turns the options into commands, in a fixed order; throws RangeError for an invalid value, before anything is sent */
+function plan(options) {
+    const steps = [];
+    if (options.locale !== undefined) {
+        if (options.locale !== null) {
+            try {
+                if (options.locale === "" || Intl.getCanonicalLocales(options.locale).length !== 1)
+                    throw new RangeError();
+            }
+            catch {
+                throw new RangeError(`emulate(): invalid locale "${options.locale}"`);
+            }
+        }
+        steps.push({ option: "locale", method: "emulation.setLocaleOverride", params: { locale: options.locale } });
+    }
+    if (options.timezone !== undefined) {
+        if (options.timezone !== null) {
+            try {
+                new Intl.DateTimeFormat(undefined, { timeZone: options.timezone });
+            }
+            catch {
+                throw new RangeError(`emulate(): unknown timezone "${options.timezone}"`);
+            }
+        }
+        steps.push({ option: "timezone", method: "emulation.setTimezoneOverride", params: { timezone: options.timezone } });
+    }
+    if (options.userAgent !== undefined) {
+        if (options.userAgent === "")
+            throw new RangeError("emulate(): userAgent must not be empty");
+        steps.push({ option: "userAgent", method: "emulation.setUserAgentOverride", params: { userAgent: options.userAgent } });
+    }
+    if (options.geolocation !== undefined) {
+        const place = options.geolocation;
+        if (place !== null) {
+            if (!isNumber(place.latitude) || place.latitude < -90 || place.latitude > 90) {
+                throw new RangeError("emulate(): latitude must be between -90 and 90");
+            }
+            if (!isNumber(place.longitude) || place.longitude < -180 || place.longitude > 180) {
+                throw new RangeError("emulate(): longitude must be between -180 and 180");
+            }
+            if (place.accuracy !== undefined && (!isNumber(place.accuracy) || place.accuracy < 0)) {
+                throw new RangeError("emulate(): accuracy must be 0 or more");
+            }
+        }
+        steps.push({
+            option: "geolocation",
+            method: "emulation.setGeolocationOverride",
+            params: { coordinates: place },
+        });
+    }
+    if (options.offline !== undefined) {
+        steps.push({
+            option: "offline",
+            method: "emulation.setNetworkConditions",
+            params: { networkConditions: options.offline ? { type: "offline" } : null },
+        });
+    }
+    if (options.orientation !== undefined) {
+        let screenOrientation = null;
+        if (options.orientation !== null) {
+            const type = (options.orientation === "portrait" || options.orientation === "landscape"
+                ? `${options.orientation}-primary`
+                : options.orientation);
+            if (!ORIENTATIONS.includes(type))
+                throw new RangeError(`emulate(): unknown orientation "${options.orientation}"`);
+            screenOrientation = { natural: type.startsWith("portrait") ? "portrait" : "landscape", type };
+        }
+        steps.push({ option: "orientation", method: "emulation.setScreenOrientationOverride", params: { screenOrientation } });
+    }
+    if (options.screen !== undefined) {
+        const area = options.screen;
+        if (area !== null && !(isPositiveInteger(area.width) && isPositiveInteger(area.height))) {
+            throw new RangeError("emulate(): screen width and height must be positive integers");
+        }
+        steps.push({ option: "screen", method: "emulation.setScreenSettingsOverride", params: { screenArea: area } });
+    }
+    if (options.touch !== undefined) {
+        if (options.touch !== null && !isPositiveInteger(options.touch)) {
+            throw new RangeError("emulate(): touch must be a positive integer");
+        }
+        steps.push({ option: "touch", method: "emulation.setTouchOverride", params: { maxTouchPoints: options.touch } });
+    }
+    if (options.javaScriptEnabled !== undefined) {
+        steps.push({
+            option: "javaScriptEnabled",
+            method: "emulation.setScriptingEnabled",
+            params: { enabled: options.javaScriptEnabled === false ? false : null },
+        });
+    }
+    return steps;
+}
+/** Throws RangeError when a value is invalid, without sending anything */
+export function validateEmulation(options) {
+    plan(options);
+}
+/**
+ * Applies the options to `target`, one command after the other. Nothing is rolled back when one fails:
+ * the error says what was applied.
+ */
+export async function applyEmulation(connector, target, options) {
+    const applied = [];
+    for (const step of plan(options)) {
+        try {
+            await connector.send(step.method, { ...step.params, ...target });
+        }
+        catch (err) {
+            if (err instanceof BiDiError && (err.code === "unknown command" || err.code === "unsupported operation")) {
+                throw new EmulationUnsupportedError(step.option, applied);
+            }
+            throw new EmulationError(step.option, applied, err);
+        }
+        applied.push(step.option);
+    }
+}

package/dist/browser/file-chooser.d.ts

@@ -0,0 +1,39 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { FileDialogInfo } from "../types/bidi-modules/input.js";
+import type { ContextTree } from "./context-tree.js";
+/**
+ * A native file picker the page asked for (a click on an `<input type=file>` or its label). Nothing appears on screen:
+ * answer it with `setFiles()`.
+ */
+export declare class FileChooser {
+    private connector;
+    private info;
+    constructor(connector: BiDiConnector, info: FileDialogInfo);
+    /** Whether the input lets the user pick several files */
+    isMultiple(): boolean;
+    /**
+     * Picks the files (an empty list picks none). Paths resolve against the working directory and must exist on the
+     * machine the browser runs on.
+     */
+    setFiles(files: string | string[]): Promise<void>;
+}
+interface EventMap {
+    filechooser: [FileChooser];
+}
+/** Follows the file pickers of one page (frames included) */
+export declare class FileChooserTracker {
+    private connector;
+    private tree;
+    private contextId;
+    private events;
+    private subscription;
+    private disposed;
+    private constructor();
+    static start(connector: BiDiConnector, tree: ContextTree, contextId: string): Promise<FileChooserTracker>;
+    on(event: "filechooser", listener: (...args: EventMap["filechooser"]) => void): void;
+    off(event: "filechooser", listener: (...args: EventMap["filechooser"]) => void): void;
+    /** Idempotent */
+    dispose(): Promise<void>;
+    private onOpened;
+}
+export {};

package/dist/browser/file-chooser.js

@@ -0,0 +1,86 @@
+import EventEmitter from "node:events";
+import logger from "../logger/index.js";
+import { assertIsFile, resolveFiles } from "./file-paths.js";
+/**
+ * A native file picker the page asked for (a click on an `<input type=file>` or its label). Nothing appears on screen:
+ * answer it with `setFiles()`.
+ */
+export class FileChooser {
+    constructor(connector, info) {
+        this.connector = connector;
+        this.info = info;
+    }
+    /** Whether the input lets the user pick several files */
+    isMultiple() {
+        return this.info.multiple;
+    }
+    /**
+     * Picks the files (an empty list picks none). Paths resolve against the working directory and must exist on the
+     * machine the browser runs on.
+     */
+    async setFiles(files) {
+        const sharedId = this.info.element?.sharedId;
+        if (!sharedId)
+            throw new Error("file chooser has no element reference");
+        const paths = resolveFiles(files);
+        for (const file of paths)
+            await assertIsFile(file, "setFiles");
+        if (paths.length > 1 && !this.info.multiple) {
+            throw new Error("file chooser does not accept multiple files");
+        }
+        await this.connector.send("input.setFiles", {
+            context: this.info.context,
+            element: { sharedId },
+            files: paths,
+        });
+    }
+}
+/** Follows the file pickers of one page (frames included) */
+export class FileChooserTracker {
+    constructor(connector, tree, contextId) {
+        this.connector = connector;
+        this.tree = tree;
+        this.contextId = contextId;
+        this.events = new EventEmitter();
+        this.disposed = false;
+        this.onOpened = (params) => {
+            if (!this.tree.isWithin(params.context, this.contextId))
+                return;
+            const chooser = new FileChooser(this.connector, params);
+            for (const listener of this.events.rawListeners("filechooser")) {
+                try {
+                    listener(chooser);
+                }
+                catch (err) {
+                    logger.error("A filechooser listener threw", { err });
+                }
+            }
+        };
+    }
+    static async start(connector, tree, contextId) {
+        const tracker = new FileChooserTracker(connector, tree, contextId);
+        connector.onEvent("input.fileDialogOpened", tracker.onOpened);
+        try {
+            tracker.subscription = await connector.subscribe(["input.fileDialogOpened"]);
+        }
+        catch (err) {
+            connector.offEvent("input.fileDialogOpened", tracker.onOpened);
+            throw err;
+        }
+        return tracker;
+    }
+    on(event, listener) {
+        this.events.on(event, listener);
+    }
+    off(event, listener) {
+        this.events.off(event, listener);
+    }
+    /** Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.connector.offEvent("input.fileDialogOpened", this.onOpened);
+        await this.subscription?.unsubscribe();
+    }
+}

package/dist/browser/file-paths.d.ts

@@ -0,0 +1,4 @@
+/** Absolute paths for `files` (relative ones resolve against the working directory) */
+export declare function resolveFiles(files: string | string[]): string[];
+/** Throws unless `file` is an existing regular file; `operation` names the caller in the message */
+export declare function assertIsFile(file: string, operation: string): Promise<void>;

package/dist/browser/file-paths.js

@@ -0,0 +1,18 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+/** Absolute paths for `files` (relative ones resolve against the working directory) */
+export function resolveFiles(files) {
+    return (Array.isArray(files) ? files : [files]).map((file) => path.resolve(file));
+}
+/** Throws unless `file` is an existing regular file; `operation` names the caller in the message */
+export async function assertIsFile(file, operation) {
+    let info;
+    try {
+        info = await stat(file);
+    }
+    catch {
+        throw new Error(`${operation}(): file not found: ${file}`);
+    }
+    if (!info.isFile())
+        throw new Error(`${operation}(): not a file: ${file}`);
+}

package/dist/browser/index.d.ts

@@ -0,0 +1,4 @@
+export { Browser, type BrowserLaunchOptions, type ContextOptions, } from "./browser.js";
+export { BrowserContext } from "./browser-context.js";
+export { default as Page } from "./page.js";
+export { findBrowser } from "./browser-finder.js";

package/dist/browser/index.js

@@ -0,0 +1,4 @@
+export { Browser, } from "./browser.js";
+export { BrowserContext } from "./browser-context.js";
+export { default as Page } from "./page.js";
+export { findBrowser } from "./browser-finder.js";

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

@@ -0,0 +1,13 @@
+import { WaitTimeoutError } from "../wait/wait-until.js";
+/** A navigation did not end in a loaded page */
+export declare class NavigationError extends Error {
+    readonly url: string;
+    readonly reason: string;
+    /** The BiDi error code, or "timeout" */
+    readonly code: string | undefined;
+    constructor(url: string, reason: string, code?: string, operation?: string);
+}
+/** The page did not reach the awaited load state in time */
+export declare class LoadStateTimeoutError extends WaitTimeoutError<undefined> {
+    constructor(state: string, timeout: number);
+}

package/dist/browser/navigation-error.js

@@ -0,0 +1,19 @@
+import { WaitTimeoutError } from "../wait/wait-until.js";
+/** A navigation did not end in a loaded page */
+export class NavigationError extends Error {
+    constructor(url, reason, code, operation = "navigateTo") {
+        super(`${operation}(): ${url} failed: ${reason}`);
+        this.name = "NavigationError";
+        this.url = url;
+        this.reason = reason;
+        this.code = code;
+    }
+}
+/** The page did not reach the awaited load state in time */
+export class LoadStateTimeoutError extends WaitTimeoutError {
+    constructor(state, timeout) {
+        super(timeout, undefined);
+        this.name = "LoadStateTimeoutError";
+        this.message = `waitForLoadState("${state}") did not finish within ${timeout}ms`;
+    }
+}

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

@@ -0,0 +1,86 @@
+import type { BiDiConnector } from "../transport/bidi-connection.js";
+import type { Level } from "../types/bidi-modules/log.js";
+import type { StackTrace } from "../types/bidi-modules/script.js";
+import type { ContextTree } from "./context-tree.js";
+/** One line of the browser's log, as kept for reports */
+export interface LogRecord {
+    level: Level;
+    /** "console", "javascript" (an uncaught exception), or another type the browser reports */
+    type: string;
+    /** The console method, for `type: "console"` */
+    method?: string;
+    text: string;
+    timestamp: number;
+}
+export interface SourceLocation {
+    url: string;
+    lineNumber: number;
+    columnNumber: number;
+}
+/** A call to `console.log`, `console.warn`, … in the page */
+export declare class ConsoleMessage {
+    /** "debug" | "info" | "warn" | "error" */
+    readonly level: Level;
+    private readonly method;
+    private readonly message;
+    /** The arguments as plain values; DOM nodes and functions stay opaque (ElementHandle, RemoteObject) */
+    readonly args: unknown[];
+    readonly timestamp: number;
+    readonly stackTrace?: StackTrace | undefined;
+    constructor(
+    /** "debug" | "info" | "warn" | "error" */
+    level: Level, method: string, message: string, 
+    /** The arguments as plain values; DOM nodes and functions stay opaque (ElementHandle, RemoteObject) */
+    args: unknown[], timestamp: number, stackTrace?: StackTrace | undefined);
+    /** The console method: "log", "warn", "error", "info", "debug", … */
+    type(): string;
+    /** What the browser prints for the call */
+    text(): string;
+    /** Where the call was made, when the browser says */
+    location(): SourceLocation | undefined;
+}
+/** An exception nobody caught in the page */
+export declare class PageError extends Error {
+    readonly timestamp: number;
+    constructor(text: string, timestamp: number, stackTrace?: StackTrace);
+}
+interface EventMap {
+    console: [ConsoleMessage];
+    pageerror: [PageError];
+}
+export type LogEventName = keyof EventMap;
+/**
+ * Collects the browser's log (`console.*` calls and uncaught exceptions) of one page, frames included,
+ * in a ring buffer, and emits `console` and `pageerror` events.
+ */
+export declare class PageLogs {
+    private connector;
+    private tree;
+    private contextId;
+    private maxEntries;
+    private events;
+    private buffer;
+    private uncaught;
+    private droppedCount;
+    private disposed;
+    private subscription;
+    private constructor();
+    static start(connector: BiDiConnector, tree: ContextTree, contextId: string, options?: {
+        maxEntries?: number;
+    }): Promise<PageLogs>;
+    /** The newest entries, oldest first (a copy) */
+    get entries(): readonly LogRecord[];
+    /** Uncaught exceptions seen since the start or the last `clear()` */
+    get errors(): readonly PageError[];
+    /** How many entries fell out of the buffer */
+    get dropped(): number;
+    on<E extends LogEventName>(event: E, listener: (...args: EventMap[E]) => void): void;
+    off<E extends LogEventName>(event: E, listener: (...args: EventMap[E]) => void): void;
+    clear(): void;
+    /** Idempotent */
+    dispose(): Promise<void>;
+    private onEntry;
+    /** A listener that throws must not stop the recording or the other listeners */
+    private emit;
+}
+export {};