@itmetsam/samurai-framework 0.7.1 → 0.9.0

package/dist/browser/download-folders.js

@@ -0,0 +1,97 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, } from "node:fs";
+import path from "node:path";
+import logger from "../logger/index.js";
+/** `report.csv` becomes `report(1).csv`, `report(2).csv`, … (the names Firefox gives) until a name is free in `dir` */
+export function uniqueName(dir, name) {
+    if (!existsSync(path.join(dir, name)))
+        return name;
+    const { name: stem, ext } = path.parse(name);
+    for (let n = 1;; n++) {
+        const candidate = `${stem}(${n})${ext}`;
+        if (!existsSync(path.join(dir, candidate)))
+            return candidate;
+    }
+}
+/**
+ * Chrome saves a download under its suggested name and replaces a file that has it already, where Firefox picks a
+ * free name. This gives every download a folder of its own while it is written (the next folder is set when a download
+ * begins) and moves the finished file into the downloads folder under a free name, so no download replaces another.
+ * Must be started before the download trackers: it rewrites `filepath` of `downloadEnd` for them.
+ */
+export class ChromeDownloadFolders {
+    constructor(connector, dir) {
+        this.connector = connector;
+        this.dir = dir;
+        this.counter = 0;
+        this.disposed = false;
+        this.onBegin = (_params) => {
+            if (this.disposed)
+                return;
+            this.rotate().catch((err) => logger.error("Could not set a new download folder", { err }));
+        };
+        this.onEnd = (params) => {
+            if (this.disposed || params.status !== "complete")
+                return;
+            try {
+                const from = params.filepath;
+                const to = path.join(this.dir, uniqueName(this.dir, path.basename(from)));
+                renameSync(from, to);
+                params.filepath = to;
+                this.removeIfEmpty(path.dirname(from));
+            }
+            catch (err) {
+                logger.error("Could not move a finished download", { err });
+            }
+        };
+    }
+    async start() {
+        this.connector.onEvent("browsingContext.downloadWillBegin", this.onBegin);
+        this.connector.onEvent("browsingContext.downloadEnd", this.onEnd);
+        try {
+            this.subscription = await this.connector.subscribe([
+                "browsingContext.downloadWillBegin",
+                "browsingContext.downloadEnd",
+            ]);
+            await this.rotate();
+        }
+        catch (err) {
+            await this.dispose();
+            throw err;
+        }
+    }
+    /** Idempotent */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.connector.offEvent("browsingContext.downloadWillBegin", this.onBegin);
+        this.connector.offEvent("browsingContext.downloadEnd", this.onEnd);
+        await this.subscription?.unsubscribe().catch(() => undefined);
+        if (this.staging)
+            this.removeIfEmpty(this.staging);
+        this.removeIfEmpty(this.stagingRoot());
+    }
+    stagingRoot() {
+        return path.join(this.dir, ".staging");
+    }
+    /** Points the browser at a new, empty folder for the download after this one */
+    async rotate() {
+        const previous = this.staging;
+        this.staging = path.join(this.stagingRoot(), String(this.counter++));
+        mkdirSync(this.staging, { recursive: true });
+        await this.connector.send("browser.setDownloadBehavior", {
+            downloadBehavior: { type: "allowed", destinationFolder: this.staging },
+        });
+        if (previous)
+            this.removeIfEmpty(previous);
+    }
+    removeIfEmpty(dir) {
+        try {
+            if (readdirSync(dir).length === 0)
+                rmSync(dir, { recursive: true });
+        }
+        catch {
+            // gone already, or not empty: leave it
+        }
+    }
+}

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

@@ -1,6 +1,7 @@
 import type { BiDiConnector } from "../transport/bidi-connection.js";
 import type { FileDialogInfo } from "../types/bidi-modules/input.js";
 import type { ContextTree } from "./context-tree.js";
+import { type FileInput } from "./generated-files.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()`.
@@ -12,10 +13,10 @@ export declare class FileChooser {
     /** 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.
+     * Picks the files (an empty list picks none). Relative paths resolve against the project folder and must exist on
+     * the machine the browser runs on; `generatedFile(…)` is accepted too.
      */
-    setFiles(files: string | string[]): Promise<void>;
+    setFiles(files: FileInput | FileInput[]): Promise<void>;
 }
 interface EventMap {
     filechooser: [FileChooser];

package/dist/browser/file-chooser.js

@@ -1,6 +1,6 @@
 import EventEmitter from "node:events";
 import logger from "../logger/index.js";
-import { assertIsFile, resolveFiles } from "./file-paths.js";
+import { resolveFileInputs } from "./generated-files.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()`.
@@ -15,16 +15,15 @@ export class FileChooser {
         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.
+     * Picks the files (an empty list picks none). Relative paths resolve against the project folder and must exist on
+     * the machine the browser runs on; `generatedFile(…)` is accepted too.
      */
     async setFiles(files) {
-        const sharedId = this.info.element?.sharedId;
+        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");
+        const paths = await resolveFileInputs(files, "setFiles");
         if (paths.length > 1 && !this.info.multiple) {
             throw new Error("file chooser does not accept multiple files");
         }
@@ -61,7 +60,9 @@ export class FileChooserTracker {
         const tracker = new FileChooserTracker(connector, tree, contextId);
         connector.onEvent("input.fileDialogOpened", tracker.onOpened);
         try {
-            tracker.subscription = await connector.subscribe(["input.fileDialogOpened"]);
+            tracker.subscription = await connector.subscribe([
+                "input.fileDialogOpened",
+            ]);
         }
         catch (err) {
             connector.offEvent("input.fileDialogOpened", tracker.onOpened);

package/dist/browser/generated-files.d.ts

@@ -0,0 +1,30 @@
+declare const GENERATED: unique symbol;
+/** A file `setInputFiles` and `dropFiles` write when the step runs, instead of one stored in the project */
+export interface GeneratedFile {
+    readonly [GENERATED]: true;
+    readonly name: string;
+    /** Bytes */
+    readonly size: number;
+    readonly type?: string;
+}
+/** What `setInputFiles` and `dropFiles` take: a path (relative to the project folder) or a generated file */
+export type FileInput = string | GeneratedFile;
+/**
+ * A file of `size` written when the step runs: seeded random bytes, the same in every run and not
+ * compressible, under `result/files/`, removed when the run ends. For upload limits and load tests.
+ * `size` is bytes or a text with a unit (`"60 MB"`, `"1.5 GB"`; powers of 1024). `type` is the MIME type
+ * `dropFiles` gives the page; for `setInputFiles` the browser takes it from the name's extension.
+ * @example
+ *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
+ */
+export declare function generatedFile(options: {
+    name: string;
+    size: number | string;
+    type?: string;
+}): GeneratedFile;
+export declare const isGeneratedFile: (value: unknown) => value is GeneratedFile;
+/** Removes this run's generated files (`withProject` calls it when the run ends) */
+export declare function removeGeneratedFiles(): Promise<void>;
+/** Absolute paths for `setInputFiles` / `dropFiles`: generated files are written, project files must exist */
+export declare function resolveFileInputs(files: FileInput | FileInput[], operation: string): Promise<string[]>;
+export {};

package/dist/browser/generated-files.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { mkdir, open, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { projectDir } from "../config/config.js";
+import { parseSize } from "../steps/files.js";
+const GENERATED = Symbol.for("samurai.generatedFile");
+const CHUNK = 1024 * 1024;
+/**
+ * A file of `size` written when the step runs: seeded random bytes, the same in every run and not
+ * compressible, under `result/files/`, removed when the run ends. For upload limits and load tests.
+ * `size` is bytes or a text with a unit (`"60 MB"`, `"1.5 GB"`; powers of 1024). `type` is the MIME type
+ * `dropFiles` gives the page; for `setInputFiles` the browser takes it from the name's extension.
+ * @example
+ *  await page.getByLabel("Upload").setInputFiles(generatedFile({ name: "huge.pdf", size: "60 MB" }));
+ */
+export function generatedFile(options) {
+    const size = parseSize(options.size);
+    if (size === undefined)
+        throw new Error(`generatedFile(): size must be a number of bytes or a text like "60 MB", got ${JSON.stringify(options.size)}`);
+    const name = path.basename(String(options.name ?? ""));
+    if (name === "" || name === "." || name === "..")
+        throw new Error(`generatedFile(): name must be a file name, got ${JSON.stringify(options.name)}`);
+    return Object.freeze({
+        [GENERATED]: true,
+        name,
+        size,
+        ...(options.type !== undefined && { type: options.type }),
+    });
+}
+export const isGeneratedFile = (value) => typeof value === "object" &&
+    value !== null &&
+    value[GENERATED] === true;
+let folder;
+const written = new Map();
+/** xorshift32, seeded from the name and size */
+function seedOf(file) {
+    const seed = createHash("sha256")
+        .update(`${file.size}:${file.name}`)
+        .digest()
+        .readUInt32LE(0);
+    return seed === 0 ? 1 : seed;
+}
+async function write(target, size, seed) {
+    const handle = await open(target, "w");
+    try {
+        const chunk = Buffer.alloc(CHUNK);
+        let state = seed;
+        for (let done = 0; done < size; done += CHUNK) {
+            for (let i = 0; i < CHUNK; i += 4) {
+                state ^= state << 13;
+                state ^= state >>> 17;
+                state ^= state << 5;
+                state >>>= 0;
+                chunk.writeUInt32LE(state, i);
+            }
+            await handle.write(chunk, 0, Math.min(CHUNK, size - done));
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** The generated file on disk; written once per run for the same name and size */
+function generatedPath(file) {
+    folder ??= path.join(projectDir(), "result", "files");
+    const key = `${file.size}/${file.name}`;
+    let pending = written.get(key);
+    if (!pending) {
+        const dir = folder;
+        pending = (async () => {
+            const target = path.join(dir, key);
+            await mkdir(path.dirname(target), { recursive: true });
+            await write(target, file.size, seedOf(file));
+            return target;
+        })();
+        written.set(key, pending);
+        pending.catch(() => written.delete(key));
+    }
+    return pending;
+}
+/** Removes this run's generated files (`withProject` calls it when the run ends) */
+export async function removeGeneratedFiles() {
+    const dir = folder;
+    folder = undefined;
+    const pending = [...written.values()];
+    written.clear();
+    await Promise.allSettled(pending);
+    if (dir)
+        await rm(dir, { recursive: true, force: true });
+}
+/** Absolute paths for `setInputFiles` / `dropFiles`: generated files are written, project files must exist */
+export async function resolveFileInputs(files, operation) {
+    const paths = [];
+    for (const file of Array.isArray(files) ? files : [files]) {
+        if (isGeneratedFile(file)) {
+            paths.push(await generatedPath(file));
+            continue;
+        }
+        if (typeof file !== "string")
+            throw new TypeError(`${operation}(): expected a path or generatedFile(…), got ${typeof file}`);
+        const absolute = path.resolve(projectDir(), file);
+        let info;
+        try {
+            info = await stat(absolute);
+        }
+        catch {
+            throw new Error(path.isAbsolute(file)
+                ? `${operation}(): file not found: ${absolute}`
+                : `${operation}(): ${file.replace(/\\/g, "/")} doesn't exist in the project`);
+        }
+        if (!info.isFile())
+            throw new Error(`${operation}(): not a file: ${absolute}`);
+        paths.push(absolute);
+    }
+    return paths;
+}

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

@@ -39,6 +39,8 @@ export declare class ConsoleMessage {
     /** Where the call was made, when the browser says */
     location(): SourceLocation | undefined;
 }
+/** The text of a page error as it reads on every browser */
+export declare function pageErrorText(text: string): string;
 /** An exception nobody caught in the page */
 export declare class PageError extends Error {
     readonly timestamp: number;

package/dist/browser/page-logs.js

@@ -28,19 +28,37 @@ export class ConsoleMessage {
     /** Where the call was made, when the browser says */
     location() {
         const frame = this.stackTrace?.callFrames[0];
-        return frame && { url: frame.url, lineNumber: frame.lineNumber, columnNumber: frame.columnNumber };
+        return (frame && {
+            url: frame.url,
+            lineNumber: frame.lineNumber,
+            columnNumber: frame.columnNumber,
+        });
     }
 }
+/**
+ * Chrome starts the text of an unhandled promise rejection with this; Firefox does not. Removed, so a page error
+ * reads the same on both browsers.
+ */
+const REJECTION_PREFIX = "Uncaught (in promise) ";
+/** The text of a page error as it reads on every browser */
+export function pageErrorText(text) {
+    return text.startsWith(REJECTION_PREFIX)
+        ? text.slice(REJECTION_PREFIX.length)
+        : text;
+}
 /** An exception nobody caught in the page */
 export class PageError extends Error {
     constructor(text, timestamp, stackTrace) {
         super(text);
         this.name = "PageError";
         this.timestamp = timestamp;
-        this.stack = [text, ...(stackTrace?.callFrames ?? []).map(formatFrame)].join("\n");
+        this.stack = [
+            text,
+            ...(stackTrace?.callFrames ?? []).map(formatFrame),
+        ].join("\n");
     }
 }
-function formatFrame({ functionName, url, lineNumber, columnNumber }) {
+function formatFrame({ functionName, url, lineNumber, columnNumber, }) {
     const where = `${url}:${lineNumber}:${columnNumber}`;
     return functionName ? `    at ${functionName} (${where})` : `    at ${where}`;
 }
@@ -68,7 +86,9 @@ export class PageLogs {
             const record = {
                 level: entry.level,
                 type: entry.type,
-                ...(entry.type === "console" && { method: entry.method }),
+                ...(entry.type === "console" && {
+                    method: entry.method,
+                }),
                 text,
                 timestamp: entry.timestamp,
             };
@@ -82,7 +102,7 @@ export class PageLogs {
                 this.emit("console", new ConsoleMessage(entry.level, consoleEntry.method, text, (consoleEntry.args ?? []).map((arg) => fromRemoteValue(arg)), entry.timestamp, entry.stackTrace));
             }
             else if (entry.type === "javascript") {
-                const error = new PageError(text, entry.timestamp, entry.stackTrace);
+                const error = new PageError(pageErrorText(text), entry.timestamp, entry.stackTrace);
                 this.uncaught.push(error);
                 if (this.uncaught.length > this.maxEntries)
                     this.uncaught.shift();

package/dist/browser/page.d.ts

@@ -46,6 +46,16 @@ interface PageEvents extends NetworkEvents {
     pageerror: [PageError];
 }
 export type PageEventName = keyof PageEvents;
+/** Events `page.waitForEvent` can wait for */
+export type WaitableEventName = "download" | "filechooser" | "request" | "response";
+export interface WaitForEventOptions<T> {
+    /** Only an event this accepts counts */
+    predicate?: (item: T) => boolean;
+    /** 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 default class Page {
     private biDiConnector;
     private id;
@@ -161,6 +171,17 @@ export default class Page {
     /** Goes forward one entry in the history. False when there is none */
     goForward(): Promise<boolean>;
     private traverse;
+    /**
+     * Whether going back would only reach the blank page a tab starts with. Firefox does not keep that page in the
+     * history, Chrome does; the Navigation API (Chrome only) lets Chrome say the same as Firefox.
+     */
+    private atFirstEntry;
+    /**
+     * Starts listening for the end of a history traversal (the new entry committed, or the history or fragment changed
+     * within the document). `done` resolves at the first such event, or after a second without one (a page restored from
+     * the back-forward cache may say nothing); it never rejects.
+     */
+    private watchHistoryTraversal;
     /** The URL of the page now */
     url(): Promise<string>;
     /** The title of the document now */
@@ -175,6 +196,13 @@ export default class Page {
         height: number;
         devicePixelRatio?: number;
     } | null): Promise<void>;
+    /**
+     * Runs `change`, then waits until the page has stopped resizing. Chrome answers a viewport reset before the window
+     * has its own size back, so a read right after it can still show the old size. The wait ends 50 ms after the last
+     * `resize` event, and after 300 ms when the size does not change at all (no event comes). Never fails: a page that
+     * cannot be watched is simply not waited for.
+     */
+    private untilResized;
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     applyDefaultViewport(): Promise<void>;
     /**
@@ -297,6 +325,15 @@ export default class Page {
         timeout?: number;
         trigger?: () => Promise<unknown>;
     }): Promise<FileChooser>;
+    /**
+     * Playwright-style wait for one page event: `download`, `filechooser`, `request` or `response`. Same as the named
+     * `waitFor…` method, with an optional predicate (a function, or `predicate` in the options). Call it before the event
+     * is caused, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const chooser = await page.waitForEvent("filechooser", { trigger: () => page.getByText("Upload file").click() });
+     *  await chooser.setFiles("./myfile.pdf");
+     */
+    waitForEvent<E extends WaitableEventName>(event: E, optionsOrPredicate?: ((item: PageEvents[E][0]) => boolean) | WaitForEventOptions<PageEvents[E][0]>): Promise<PageEvents[E][0]>;
     /**
      * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
      * when this ran before the request started. `page.on("response")` and `waitForResponse` call it; config

package/dist/browser/page.js

@@ -31,6 +31,8 @@ import { LoadStateTimeoutError, NavigationError } from "./navigation-error.js";
 import { callFunction } from "../script/call-function.js";
 /** Time (ms) a navigation or a wait for a load state may take */
 const DEFAULT_NAVIGATION_TIMEOUT = 30000;
+/** Time (ms) a history traversal may go without a sign that the entry is shown before it is taken as done */
+const HISTORY_SETTLE_TIMEOUT = 1000;
 /** Time (ms) without requests in flight that counts as idle */
 const DEFAULT_IDLE_TIME = 500;
 /** The size a page gets unless config `use.viewport` says otherwise */
@@ -336,11 +338,17 @@ export default class Page {
     }
     async traverse(delta) {
         this.assertOpen();
+        if (delta === -1 && (await this.atFirstEntry()))
+            return false;
+        const settled = await this.watchHistoryTraversal();
         try {
             await this.biDiConnector.send("browsingContext.traverseHistory", {
                 context: this.id,
                 delta,
             });
+            // Firefox answers once the entry is shown; Chrome answers before, and a script call in between can hit the
+            // document that is going away
+            await settled.done;
             return true;
         }
         catch (err) {
@@ -348,6 +356,66 @@ export default class Page {
                 return false;
             throw err;
         }
+        finally {
+            await settled.stop();
+        }
+    }
+    /**
+     * Whether going back would only reach the blank page a tab starts with. Firefox does not keep that page in the
+     * history, Chrome does; the Navigation API (Chrome only) lets Chrome say the same as Firefox.
+     */
+    async atFirstEntry() {
+        try {
+            return await callFunction(this.biDiConnector, this.id, `() => {
+          const nav = globalThis.navigation;
+          if (!nav) return false;
+          const entries = nav.entries();
+          const index = nav.currentEntry.index;
+          return index === 0 || (index === 1 && entries[0].url === "about:blank");
+        }`, [], { awaitPromise: false });
+        }
+        catch (err) {
+            logger.debug("Could not read the history position", { err });
+            return false;
+        }
+    }
+    /**
+     * Starts listening for the end of a history traversal (the new entry committed, or the history or fragment changed
+     * within the document). `done` resolves at the first such event, or after a second without one (a page restored from
+     * the back-forward cache may say nothing); it never rejects.
+     */
+    async watchHistoryTraversal() {
+        const events = [
+            "browsingContext.navigationCommitted",
+            "browsingContext.historyUpdated",
+            "browsingContext.fragmentNavigated",
+        ];
+        let subscription;
+        try {
+            subscription = await this.biDiConnector.subscribe([...events]);
+        }
+        catch (err) {
+            logger.debug("Could not watch a history traversal", { err });
+            return { done: Promise.resolve(), stop: async () => { } };
+        }
+        let finish;
+        const done = new Promise((resolve) => (finish = resolve));
+        const timer = setTimeout(finish, HISTORY_SETTLE_TIMEOUT);
+        const listener = (info) => {
+            if (info.context === this.id)
+                finish();
+        };
+        for (const event of events)
+            this.biDiConnector.onEvent(event, listener);
+        return {
+            done,
+            stop: async () => {
+                clearTimeout(timer);
+                for (const event of events)
+                    this.biDiConnector.offEvent(event, listener);
+                await subscription?.unsubscribe().catch(() => undefined);
+            },
+        };
     }
     /** The URL of the page now */
     async url() {
@@ -367,11 +435,11 @@ export default class Page {
     async setViewport(viewport) {
         this.assertOpen();
         if (viewport === null) {
-            await this.biDiConnector.send("browsingContext.setViewport", {
+            await this.untilResized(() => this.biDiConnector.send("browsingContext.setViewport", {
                 context: this.id,
                 viewport: null,
                 devicePixelRatio: null,
-            });
+            }));
             return;
         }
         const { width, height, devicePixelRatio } = viewport;
@@ -393,6 +461,35 @@ export default class Page {
             ...(devicePixelRatio !== undefined && { devicePixelRatio }),
         });
     }
+    /**
+     * Runs `change`, then waits until the page has stopped resizing. Chrome answers a viewport reset before the window
+     * has its own size back, so a read right after it can still show the old size. The wait ends 50 ms after the last
+     * `resize` event, and after 300 ms when the size does not change at all (no event comes). Never fails: a page that
+     * cannot be watched is simply not waited for.
+     */
+    async untilResized(change) {
+        const sandbox = { sandbox: "samurai-viewport" };
+        const watching = await callFunction(this.biDiConnector, this.id, `() => {
+        globalThis.__resized = new Promise((resolve) => {
+          let timer;
+          const finish = () => {
+            clearTimeout(timer);
+            removeEventListener("resize", onResize);
+            resolve();
+          };
+          const onResize = () => {
+            clearTimeout(timer);
+            timer = setTimeout(finish, 50);
+          };
+          addEventListener("resize", onResize);
+          timer = setTimeout(finish, 300);
+        });
+      }`, [], { ...sandbox, awaitPromise: false }).then(() => true, () => false);
+        await change();
+        if (!watching)
+            return;
+        await callFunction(this.biDiConnector, this.id, "() => globalThis.__resized", [], sandbox).catch(() => undefined);
+    }
     /** Gives the page the size from config `use.viewport` (1280x720 by default); the browser does this when it opens a page */
     async applyDefaultViewport() {
         const { viewport } = this.settings?.use ?? (await readSection("use"));
@@ -784,6 +881,36 @@ export default class Page {
         await this.startFileChooserTracking();
         return this.waitForPageEvent("filechooser", () => true, options, (timeout) => new FileChooserTimeoutError(timeout));
     }
+    /**
+     * Playwright-style wait for one page event: `download`, `filechooser`, `request` or `response`. Same as the named
+     * `waitFor…` method, with an optional predicate (a function, or `predicate` in the options). Call it before the event
+     * is caused, or pass `trigger`, which runs once the wait is set up.
+     * @example
+     *  const chooser = await page.waitForEvent("filechooser", { trigger: () => page.getByText("Upload file").click() });
+     *  await chooser.setFiles("./myfile.pdf");
+     */
+    async waitForEvent(event, optionsOrPredicate = {}) {
+        const { predicate, ...options } = typeof optionsOrPredicate === "function"
+            ? { predicate: optionsOrPredicate }
+            : optionsOrPredicate;
+        const accepts = (predicate ?? (() => true));
+        switch (event) {
+            case "request":
+                return this.waitForRequest(accepts, options);
+            case "response":
+                return this.waitForResponse(accepts, options);
+            case "download":
+                this.assertOpen();
+                await this.startDownloadTracking();
+                return this.waitForPageEvent("download", accepts, options, (timeout) => new DownloadWaitTimeoutError(timeout));
+            case "filechooser":
+                this.assertOpen();
+                await this.startFileChooserTracking();
+                return this.waitForPageEvent("filechooser", accepts, options, (timeout) => new FileChooserTimeoutError(timeout));
+            default:
+                throw new Error(`page.waitForEvent() does not support "${String(event)}": use page.on()`);
+        }
+    }
     /**
      * Starts keeping response bodies, which is what makes `response.body()` possible: the browser only keeps a body
      * when this ran before the request started. `page.on("response")` and `waitForResponse` call it; config

package/dist/browser/screenshot.js

@@ -1,5 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { callFunction } from "../script/call-function.js";
+import { ElementHandle } from "../script/element-handle.js";
 const MIME = { png: "image/png", jpeg: "image/jpeg" };
 /** The `format` of a capture command; validates the type/quality combination */
 function imageFormat({ type, quality, }) {
@@ -23,12 +25,17 @@ function imageFormat({ type, quality, }) {
  */
 export async function takeScreenshot(connector, context, options = {}, element) {
     const format = imageFormat(options);
+    // An element is captured as its box in the document: Chrome cannot capture an `element` clip that is not
+    // wholly in the viewport, and this works the same for an element taller than the viewport
     const clip = element
-        ? { type: "element", element: { sharedId: element.sharedId } }
+        ? {
+            type: "box",
+            ...(await documentBox(connector, context, element)),
+        }
         : options.clip && { type: "box", ...options.clip };
     const { data } = await connector.send("browsingContext.captureScreenshot", {
         context,
-        ...(options.fullPage && { origin: "document" }),
+        ...((options.fullPage || element) && { origin: "document" }),
         ...(format && { format }),
         ...(clip && { clip }),
     });
@@ -36,6 +43,13 @@ export async function takeScreenshot(connector, context, options = {}, element)
     await writeOutput(options.path, image);
     return image;
 }
+/** The element's box in document coordinates (CSS pixels) */
+async function documentBox(connector, context, element) {
+    return callFunction(connector, context, `(el) => {
+      const r = el.getBoundingClientRect();
+      return { x: r.x + scrollX, y: r.y + scrollY, width: r.width, height: r.height };
+    }`, [new ElementHandle(element.sharedId)]);
+}
 /** Writes `data` to `file`, creating the folders; nothing happens without a path */
 export async function writeOutput(file, data) {
     if (!file)