@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/browser/dialogs.js

@@ -0,0 +1,271 @@
+import { Deadline } from "../protocol/deadline.js";
+import { isDialogType, unwaitedDialogMessage, unwaitedDialogSentence } from "../protocol/dialogs.js";
+import { errorMessage, failureSchema } from "../protocol/failures.js";
+import { parse, s } from "../protocol/schema.js";
+import { readProtocol, sendOptions } from "./cdp-results.js";
+import { CdpClosedError, CdpDisconnectedError } from "./cdp/errors.js";
+import { Listeners } from "./listeners.js";
+// Every part but the kind is read leniently: a dialog whose event Retest could not read would hold the page for good.
+const openingSchema = s.object({ type: s.string(), message: s.optional(s.string()), defaultPrompt: s.optional(s.string()) });
+const closedSchema = s.object({ result: s.boolean() });
+/**
+ * The JavaScript dialogs of one Chromium page. A dialog holds the page until it is answered: the command whose input
+ * opened it waits, as Chrome does not answer that input before then. A page armed with `arm` hands its next dialog to
+ * the test, which answers it with `answer`. Any other dialog Retest answers at once, dismissing it, or accepting a
+ * `beforeunload` so the navigation the test asked for happens, and tells its listeners; a command running meanwhile
+ * fails with it, so no dialog is ever answered silently as a pass.
+ */
+export class PageDialogs {
+    #session;
+    #unwaited;
+    #closed;
+    // Every dialog Retest answered itself, in order, so a command can tell which arrived while it ran.
+    #answeredByRetest = [];
+    // How many `beforeunload` dialogs were dismissed, each keeping the page where it was.
+    #pagesKept = 0;
+    #waiter;
+    #open;
+    #opened = 0;
+    #running = 0;
+    #lostReason;
+    constructor(session, onListenerError) {
+        this.#session = session;
+        this.#unwaited = new Listeners(onListenerError);
+        this.#closed = new Listeners(onListenerError);
+    }
+    /** The kind of the dialog open on the page, while one is. */
+    get open() {
+        return this.#open?.type;
+    }
+    /** The dialog the test was given and has not answered, which holds the page until it does. */
+    get held() {
+        const open = this.#open;
+        return open?.by === 'test' && open.answering !== true ? open : undefined;
+    }
+    /**
+     * Arms the page for its next dialog, at once, so a command sent after this call cannot open a dialog Retest would
+     * answer itself. The wait settles with that dialog, or fails when `timeoutMs` runs out, when `signal` aborts, with its
+     * reason when that is a `Failure`, or when the page goes. One wait at a time.
+     */
+    arm(timeoutMs, signal) {
+        if (this.#lostReason !== undefined)
+            return { ok: false, failure: lost(this.#lostReason) };
+        if (this.#waiter !== undefined)
+            return { ok: false, failure: { class: 'usage', message: 'page.dialog() is already waiting for a dialog on this page. Await it before the next one.' } };
+        const deadline = new Deadline(timeoutMs, { signal });
+        const { promise, resolve } = Promise.withResolvers();
+        const timer = setTimeout(() => settle({ ok: false, failure: { class: 'timeout', message: `No dialog opened within ${deadline.budgetMs} ms.` } }), deadline.waitToEndMs);
+        const stop = () => settle({ ok: false, failure: stopped(signal?.reason) });
+        const waiter = { settle: (wait) => settle(wait) };
+        const settle = (wait) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', stop);
+            if (this.#waiter === waiter)
+                this.#waiter = undefined;
+            resolve(wait);
+        };
+        this.#waiter = waiter;
+        if (signal?.aborted === true)
+            stop();
+        else
+            signal?.addEventListener('abort', stop, { once: true });
+        return { ok: true, opened: promise };
+    }
+    /**
+     * Answers the dialog the test was given, accepting it with a prompt's text or dismissing it, within `timeoutMs`.
+     * A dialog that is no longer open, or one the test was not given, fails and nothing is sent.
+     */
+    async answer(id, reply, timeoutMs) {
+        const open = this.#open;
+        if (open === undefined || open.id !== id || open.by !== 'test' || open.answering === true) {
+            const message = this.#lostReason === undefined ? 'The dialog is no longer open, so Retest answered nothing.' : `The page is gone, so Retest answered nothing: ${this.#lostReason}.`;
+            return { ok: false, failure: { class: 'not_actionable', message } };
+        }
+        if (reply.promptText !== undefined && open.type !== 'prompt') {
+            return { ok: false, failure: { class: 'usage', message: `accept() takes text only for a prompt dialog, and this is ${article(open.type)} ${open.type} dialog.` } };
+        }
+        // Chrome answers a prompt accepted with no text with an empty one; a person who presses OK submits the default.
+        const promptText = reply.promptText ?? (reply.accept && open.type === 'prompt' ? open.defaultValue : undefined);
+        const params = { accept: reply.accept, ...(promptText === undefined ? {} : { promptText }) };
+        open.answering = true;
+        // Chrome answers the navigation a dismissed beforeunload stopped before it says the dialog closed, so it is counted now.
+        if (open.type === 'beforeunload' && !reply.accept)
+            this.#pagesKept += 1;
+        try {
+            await this.#session.send('Page.handleJavaScriptDialog', params, sendOptions(new Deadline(timeoutMs)));
+            return { ok: true };
+        }
+        catch (error) {
+            if (error instanceof CdpDisconnectedError || error instanceof CdpClosedError)
+                return { ok: false, failure: lost(error.reason) };
+            return { ok: false, failure: { class: 'outcome_unknown', message: `Retest asked the browser to answer the ${open.type} dialog, and could not tell whether it did: ${errorMessage(error)}` } };
+        }
+    }
+    /**
+     * Takes on the dialogs Retest answered on the page before the page was set up, as an Electron app's first window can
+     * show one as it loads. Listeners hear them first, as dialogs nothing waited for that opened while no command ran.
+     */
+    answeredBefore(dialogs) {
+        this.#answeredByRetest.push(...dialogs);
+    }
+    /**
+     * Hears each dialog Retest answered itself, those before the call first, since a popup runs before whoever waits for
+     * it can listen. Returns a function that stops listening.
+     */
+    onUnwaited(listener) {
+        for (const dialog of this.#answeredByRetest)
+            listener(dialog);
+        return this.#unwaited.add(listener);
+    }
+    /**
+     * Tells of a dialog Retest answered in a page this page opened while nothing waited for it, as this page's own: a
+     * command running here fails with it, and the listeners hear it.
+     */
+    forward(dialog) {
+        const told = { ...dialog, during: this.#running > 0, popup: true };
+        this.#answeredByRetest.push(told);
+        this.#unwaited.emit(told);
+    }
+    /** Hears each dialog that closed, however it was answered. Returns a function that stops listening. */
+    onClosed(listener) {
+        return this.#closed.add(listener);
+    }
+    /**
+     * Marks a command running on the page. The function it returns marks it over, and says what dialogs did meanwhile:
+     * the first Retest answered itself, which the command then fails with, and whether a `beforeunload` dialog was
+     * dismissed, which kept the page where it was.
+     */
+    commandStarted() {
+        const from = this.#answeredByRetest.length;
+        const kept = this.#pagesKept;
+        this.#running += 1;
+        return () => {
+            this.#running -= 1;
+            return { unwaited: this.#answeredByRetest[from], kept: this.#pagesKept > kept };
+        };
+    }
+    /** Reads `Page.javascriptDialogOpening`: hands the dialog to the test that waits for it, or answers it at once. */
+    opened(params) {
+        const { type, message = '', defaultPrompt } = readProtocol(openingSchema, params, { method: 'Page.javascriptDialogOpening', sessionId: this.#session.id });
+        // A kind this release does not know is handled as an alert is, so the page is never left held.
+        const kind = isDialogType(type) ? type : 'alert';
+        this.#opened += 1;
+        const dialog = { id: `dialog-${this.#opened}`, type: kind, message, defaultValue: kind === 'prompt' ? (defaultPrompt ?? '') : '' };
+        const waiter = this.#waiter;
+        if (waiter !== undefined) {
+            this.#open = { ...dialog, by: 'test' };
+            waiter.settle({ ok: true, dialog });
+            return;
+        }
+        const accept = kind === 'beforeunload';
+        this.#open = { ...dialog, by: 'retest', answering: true };
+        const unwaited = { type: kind, message, answered: accept ? 'accepted' : 'dismissed', during: this.#running > 0 };
+        this.#answeredByRetest.push(unwaited);
+        this.#session.send('Page.handleJavaScriptDialog', { accept }).catch(() => {
+            // A page that went away took its dialog with it; a command waiting on it hears of the loss itself.
+        });
+        this.#unwaited.emit(unwaited);
+    }
+    /** Reads `Page.javascriptDialogClosed`. */
+    closed(params) {
+        const open = this.#open;
+        this.#open = undefined;
+        if (open === undefined)
+            return;
+        const { result } = readProtocol(closedSchema, params, { method: 'Page.javascriptDialogClosed', sessionId: this.#session.id });
+        this.#closed.emit({ type: open.type, accepted: result });
+    }
+    /** The page went away: a wait fails with the reason, and no dialog is open any more. */
+    lost(reason) {
+        this.#lostReason ??= reason;
+        this.#open = undefined;
+        this.#waiter?.settle({ ok: false, failure: lost(reason) });
+    }
+}
+/**
+ * The failure of a command during which the page opened a dialog nothing waited for, which Retest answered. `command`
+ * is the command as a failure names it. The dialog's text is page text: it goes in `details.dialogMessage`, as the page
+ * showed it, for the parent to redact and quote, and the message leaves it out.
+ *
+ * @example unwaitedDialogFailure("click getByTestId('delete')", dialog, true).class // 'not_actionable'
+ */
+export function unwaitedDialogFailure(command, dialog, inputSent) {
+    const popup = dialog.popup === true ? { popup: true } : {};
+    return {
+        class: 'not_actionable',
+        message: unwaitedDialogMessage({ type: dialog.type, answered: dialog.answered, command, popup: dialog.popup === true }),
+        details: { dialog: dialog.type, dialogMessage: dialog.message, answered: dialog.answered, command, ...popup, inputSent },
+    };
+}
+/**
+ * A command's own failure, with the dialog Retest answered while it ran named after it: the command's class, message
+ * and details stay first, since its outcome is what happened, and the dialog follows in a sentence of its own and in
+ * `details`. The dialog's text goes in `details.dialogMessage` for the parent to redact and quote.
+ *
+ * @example withUnwaitedDialog(timedOut, dialog).class // 'timeout'
+ */
+export function withUnwaitedDialog(failure, dialog) {
+    const popup = dialog.popup === true ? { popup: true } : {};
+    return {
+        ...failure,
+        message: `${failure.message} ${unwaitedDialogSentence({ type: dialog.type, answered: dialog.answered, popup: dialog.popup === true })}`,
+        details: { ...failure.details, dialog: dialog.type, dialogMessage: dialog.message, answered: dialog.answered, ...popup },
+    };
+}
+/**
+ * The failure of a command the page did not follow because a `beforeunload` dialog was dismissed, which keeps the page
+ * where it was.
+ *
+ * @example keptByBeforeunload('open http://127.0.0.1:4173/next', true).class // 'not_actionable'
+ */
+export function keptByBeforeunload(command, inputSent) {
+    return { class: 'not_actionable', message: `Retest could not ${command}: its beforeunload dialog was dismissed, so the page stayed where it was.`, details: { dialog: 'beforeunload', inputSent } };
+}
+/**
+ * A command's own failure of another kind, as a timeout, while a `beforeunload` dialog the test dismissed kept the page:
+ * its class and message stay first, and the kept page follows.
+ *
+ * @example withKeptPage(timedOut).message.endsWith('so the page stayed where it was.') // true
+ */
+export function withKeptPage(failure) {
+    return { ...failure, message: `${failure.message} Its beforeunload dialog was dismissed, so the page stayed where it was.`, details: { ...failure.details, dialog: 'beforeunload' } };
+}
+/**
+ * The failure of a command that met a dialog the test was given and has not answered, which holds the page: one sent
+ * while it holds the page, which sends nothing, or the command whose input opened it and whose time ran out waiting.
+ *
+ * @example heldByDialog("click getByTestId('save')", 'confirm', false).class // 'not_actionable'
+ */
+export function heldByDialog(command, type, inputSent) {
+    if (inputSent) {
+        return {
+            class: 'timeout',
+            message: `Retest began to ${command}, and the ${type} dialog the test was given held the page until the time ran out. Answer it with dialog.accept() or dialog.dismiss().`,
+            details: { dialog: type, inputSent: true },
+        };
+    }
+    return {
+        class: 'not_actionable',
+        message: `Retest could not ${command}: the ${type} dialog the test was given still holds the page. Answer it first with dialog.accept() or dialog.dismiss().`,
+        details: { dialog: type, inputSent: false },
+    };
+}
+/**
+ * The refusal of `page.dialog()` on a page of an engine that cannot hand its dialogs to a test yet.
+ *
+ * @example dialogsUnsupported('Firefox').class // 'unsupported'
+ */
+export function dialogsUnsupported(engine) {
+    return { class: 'unsupported', message: `Retest hands dialogs to a test on Chrome and Chromium only, and not on ${engine} yet.` };
+}
+function lost(reason) {
+    return { class: 'session_lost', message: `The page went away before a dialog was answered: ${reason}.` };
+}
+// A wait stopped by its test or its caller says why, with the class the reason gives.
+function stopped(reason) {
+    const parsed = parse(failureSchema, reason);
+    return parsed.ok ? parsed.value : { class: 'interrupted', message: 'Retest stopped waiting for a dialog.' };
+}
+function article(word) {
+    return /^[aeiou]/.test(word) ? 'an' : 'a';
+}

package/dist/browser/downloads.d.ts

@@ -0,0 +1,71 @@
+import type { CdpConnection } from './cdp/connection.ts';
+import type { CdpSession } from './cdp/session.ts';
+import type { DownloadStart, PageDownload } from './contract.ts';
+import type { Deadline } from '../protocol/deadline.ts';
+/** A download as the browser began it, before its page is known. */
+type Began = {
+    guid: string;
+    url: string;
+    suggestedFilename: string;
+};
+type Progress = {
+    guid: string;
+    totalBytes: number;
+    receivedBytes: number;
+    state: 'inProgress' | 'completed' | 'canceled';
+    filePath?: string | undefined;
+};
+/** What a page's downloads are told of it: its session, its main frame as it stands, its context, and whether it is a popup. */
+export type PageDownloadsOptions = {
+    session: CdpSession;
+    mainFrame: () => string;
+    browserContextId: string;
+    popup: boolean;
+};
+/**
+ * The browser's downloads, each routed to the test's page of the context it began in. A download begun by that page or
+ * a frame inside it is the page's own. One begun by a page it opened, or by a frame of such a page, is told as begun in
+ * a popup; any other download of the context, as begun in another page. A download whose frame Retest was told of in no
+ * way is placed once it is saved, by the folder it was saved in, as begun in another page.
+ */
+export declare class BrowserDownloads {
+    #private;
+    constructor(connection: CdpConnection, onListenerError: (error: unknown) => void);
+    /**
+     * Tells the browser what to do with a context's downloads: save each in `folder`, named by its id until Retest names
+     * it, and say how each goes; or, without a folder, refuse them, so none lands in the person's own Downloads folder.
+     * The first context that saves them has the browser tell of every target it makes from then on.
+     *
+     * @example await downloads.configure(browserContextId, '/run/artifacts/k3v9q0x2mb/web-1a2b/downloads', deadline)
+     */
+    configure(browserContextId: string, folder: string | undefined, deadline: Deadline): Promise<void>;
+    /** The downloads of one page, until `close` is called on them. */
+    page(options: PageDownloadsOptions): PageDownloads;
+}
+type PageDownloadsParts = PageDownloadsOptions & {
+    onListenerError: (error: unknown) => void;
+    closed: () => void;
+};
+/**
+ * The downloads one page is told of: those begun in its main frame and in the frames inside it, which the page tells of
+ * as they attach and detach, and, for the test's own page of a context, those begun anywhere else in its context.
+ */
+export declare class PageDownloads {
+    #private;
+    readonly mainFrame: () => string;
+    readonly context: string;
+    readonly popup: boolean;
+    constructor({ session, mainFrame, browserContextId, popup, onListenerError, closed }: PageDownloadsParts);
+    /** Whether the frame is this page's: its main frame, or a frame inside it the page told of. */
+    holds(frameId: string): boolean;
+    /** Tells `listener` of every download the page is told of from now on. Returns a function that removes it. */
+    onDownload(listener: (download: PageDownload) => void): () => void;
+    began({ guid, url, suggestedFilename, startedIn }: Began & {
+        startedIn?: DownloadStart;
+    }): void;
+    progressed({ guid, receivedBytes, totalBytes, state, filePath }: Progress): void;
+    /** Stops routing downloads to this page and tells no listener of any more. A download on its way is left as it is. */
+    close(): void;
+}
+export {};
+//# sourceMappingURL=downloads.d.ts.map

package/dist/browser/downloads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloads.d.ts","sourceRoot":"","sources":["../../src/browser/downloads.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAe,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC7E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AA6BvD,oEAAoE;AACpE,KAAK,KAAK,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAA;AAErE,KAAK,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAE1J,gIAAgI;AAChI,MAAM,MAAM,oBAAoB,GAAG;IAAE,OAAO,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAK7H;;;;;GAKG;AACH,qBAAa,gBAAgB;;gBAaf,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;IAShF;;;;;;OAMG;IACG,SAAS,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IASxG,kEAAkE;IAClE,IAAI,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa;CAuGnD;AAED,KAAK,kBAAkB,GAAG,oBAAoB,GAAG;IAAE,eAAe,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CAAA;AAKlH;;;GAGG;AACH,qBAAa,aAAa;;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,CAAA;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;gBAOX,EAAE,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,EAAE,kBAAkB;IAiBxG,+FAA+F;IAC/F,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI/B,8GAA8G;IAC9G,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI;IAIlE,KAAK,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,iBAAiB,EAAE,SAAS,EAAE,EAAE,KAAK,GAAG;QAAE,SAAS,CAAC,EAAE,aAAa,CAAA;KAAE,GAAG,IAAI;IAmB/F,UAAU,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,QAAQ,GAAG,IAAI;IAYhF,sHAAsH;IACtH,KAAK,IAAI,IAAI;CAMd"}

package/dist/browser/downloads.js

@@ -0,0 +1,253 @@
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { s } from "../protocol/schema.js";
+import { readProtocol, request, sendOptions } from "./cdp-results.js";
+import { Listeners } from "./listeners.js";
+// Chrome tells of a download on the browser's own session, by the frame that began it, whatever context the frame is
+// in, so the browser routes each one to the test's page of the context the frame is in. `Page.downloadWillBegin` would
+// come on the page's session, but Chrome marks it deprecated in favour of these. A page a page opens, as a link with
+// `target="_blank"` does, is a target of its own, often gone a moment after its download begins, so the browser keeps
+// what it was told of every page and frame target in a context that saves downloads, from the moment it is made.
+const willBeginSchema = s.object({ frameId: s.string(), guid: s.string(), url: s.string(), suggestedFilename: s.string() });
+const progressSchema = s.object({
+    guid: s.string(),
+    totalBytes: s.number({ min: 0 }),
+    receivedBytes: s.number({ min: 0 }),
+    state: s.enum(['inProgress', 'completed', 'canceled']),
+    filePath: s.optional(s.string()),
+});
+const targetSchema = s.object({
+    targetInfo: s.object({ targetId: s.string(), type: s.string(), browserContextId: s.optional(s.string()), openerId: s.optional(s.string()), parentId: s.optional(s.string()) }),
+});
+const frameSchema = s.object({ frameId: s.string() });
+const navigatedSchema = s.object({ frame: s.object({ id: s.string(), parentId: s.optional(s.string()) }) });
+// How far a frame or a popup is followed back to the page that holds it: a popup's popup's frame is three steps.
+const maxSteps = 8;
+/**
+ * The browser's downloads, each routed to the test's page of the context it began in. A download begun by that page or
+ * a frame inside it is the page's own. One begun by a page it opened, or by a frame of such a page, is told as begun in
+ * a popup; any other download of the context, as begun in another page. A download whose frame Retest was told of in no
+ * way is placed once it is saved, by the folder it was saved in, as begun in another page.
+ */
+export class BrowserDownloads {
+    #connection;
+    #onListenerError;
+    #pages = new Set();
+    // The folder each context that saves downloads saves them in, by context.
+    #folders = new Map();
+    #targets = new Map();
+    // The page each download on its way was told to, by the download's id, until it ends or that page closes.
+    #owners = new Map();
+    // Downloads no page could be found for as they began, by id, until they end.
+    #unplaced = new Map();
+    #discovering;
+    constructor(connection, onListenerError) {
+        this.#connection = connection;
+        this.#onListenerError = onListenerError;
+        connection.on('Browser.downloadWillBegin', (params) => this.#guarded(() => this.#began(params)));
+        connection.on('Browser.downloadProgress', (params) => this.#guarded(() => this.#progressed(params)));
+        connection.on('Target.targetCreated', (params) => this.#guarded(() => this.#targetTold(params)));
+        connection.on('Target.targetInfoChanged', (params) => this.#guarded(() => this.#targetTold(params)));
+    }
+    /**
+     * Tells the browser what to do with a context's downloads: save each in `folder`, named by its id until Retest names
+     * it, and say how each goes; or, without a folder, refuse them, so none lands in the person's own Downloads folder.
+     * The first context that saves them has the browser tell of every target it makes from then on.
+     *
+     * @example await downloads.configure(browserContextId, '/run/artifacts/k3v9q0x2mb/web-1a2b/downloads', deadline)
+     */
+    async configure(browserContextId, folder, deadline) {
+        if (folder !== undefined) {
+            this.#folders.set(browserContextId, resolve(folder));
+            await this.#discover(deadline);
+        }
+        const behavior = folder === undefined ? { behavior: 'deny', browserContextId } : { behavior: 'allowAndName', browserContextId, downloadPath: folder, eventsEnabled: true };
+        await request(this.#connection, 'Browser.setDownloadBehavior', behavior, s.object({}), sendOptions(deadline));
+    }
+    /** The downloads of one page, until `close` is called on them. */
+    page(options) {
+        const downloads = new PageDownloads({ ...options, onListenerError: this.#onListenerError, closed: () => this.#closed(downloads) });
+        this.#pages.add(downloads);
+        return downloads;
+    }
+    // A start that failed is tried again by the next page that saves downloads.
+    #discover(deadline) {
+        const discovering = (this.#discovering ??= request(this.#connection, 'Target.setDiscoverTargets', { discover: true }, s.object({}), sendOptions(deadline)).then(() => undefined));
+        discovering.catch(() => {
+            if (this.#discovering === discovering)
+                this.#discovering = undefined;
+        });
+        return discovering;
+    }
+    #targetTold(params) {
+        const { targetId, type, browserContextId, openerId, parentId } = readProtocol(targetSchema, params, { method: 'Target.targetCreated' }).targetInfo;
+        if ((type !== 'page' && type !== 'iframe') || browserContextId === undefined || !this.#folders.has(browserContextId))
+            return;
+        const known = this.#targets.get(targetId);
+        this.#targets.set(targetId, { context: browserContextId, opener: openerId ?? known?.opener, parent: parentId ?? known?.parent });
+    }
+    #began(params) {
+        const { frameId, guid, url, suggestedFilename } = readProtocol(willBeginSchema, params, { method: 'Browser.downloadWillBegin' });
+        const holder = [...this.#pages].find((page) => page.holds(frameId));
+        const target = this.#targets.get(frameId);
+        const context = holder?.context ?? target?.context;
+        const home = context === undefined ? undefined : this.#home(context);
+        if (home === undefined) {
+            this.#unplaced.set(guid, { guid, url, suggestedFilename });
+            return;
+        }
+        const startedIn = holder === home ? undefined : holder !== undefined && holder.popup ? this.#openedBy(holder.mainFrame(), home) : this.#startOf(frameId, home);
+        this.#owners.set(guid, home);
+        home.began({ guid, url, suggestedFilename, ...(startedIn === undefined ? {} : { startedIn }) });
+    }
+    #progressed(params) {
+        const progress = readProtocol(progressSchema, params, { method: 'Browser.downloadProgress' });
+        const final = progress.state !== 'inProgress';
+        const owner = this.#owners.get(progress.guid);
+        if (owner !== undefined) {
+            if (final)
+                this.#owners.delete(progress.guid);
+            owner.progressed(progress);
+            return;
+        }
+        const began = this.#unplaced.get(progress.guid);
+        if (began === undefined || !final)
+            return;
+        this.#unplaced.delete(progress.guid);
+        const home = progress.filePath === undefined ? undefined : this.#homeByFolder(dirname(progress.filePath));
+        if (home === undefined)
+            return;
+        home.began({ ...began, startedIn: 'other' });
+        home.progressed(progress);
+    }
+    // The test's page of a context: the one page of it that is no popup.
+    #home(context) {
+        return [...this.#pages].find((page) => page.context === context && !page.popup);
+    }
+    #homeByFolder(folder) {
+        const context = [...this.#folders].find(([, saved]) => saved === resolve(folder))?.[0];
+        return context === undefined ? undefined : this.#home(context);
+    }
+    // Where a frame target stands to the page: a frame inside it, a page it opened or a frame of one, or another page.
+    #startOf(targetId, home) {
+        let current = targetId;
+        let opened = false;
+        for (let step = 0; step < maxSteps && current !== undefined; step += 1) {
+            if (current === home.mainFrame())
+                return opened ? 'popup' : undefined;
+            const facts = this.#targets.get(current);
+            if (facts?.parent !== undefined)
+                current = facts.parent;
+            else {
+                opened = true;
+                current = facts?.opener;
+            }
+        }
+        return 'other';
+    }
+    // A popup page Retest opened is the test's when the page or a page it opened opened it.
+    #openedBy(popupFrame, home) {
+        return this.#startOf(popupFrame, home) === 'popup' ? 'popup' : 'other';
+    }
+    // A page that closes takes the downloads still on their way to it, and the facts of its context, with it.
+    #closed(page) {
+        this.#pages.delete(page);
+        for (const [guid, owner] of this.#owners)
+            if (owner === page)
+                this.#owners.delete(guid);
+        if (page.popup)
+            return;
+        this.#folders.delete(page.context);
+        for (const [targetId, facts] of this.#targets)
+            if (facts.context === page.context)
+                this.#targets.delete(targetId);
+    }
+    // An event Retest cannot read must not reach the connection, which would drop the browser's other events with it.
+    #guarded(work) {
+        try {
+            work();
+        }
+        catch (error) {
+            this.#onListenerError(error);
+        }
+    }
+}
+/**
+ * The downloads one page is told of: those begun in its main frame and in the frames inside it, which the page tells of
+ * as they attach and detach, and, for the test's own page of a context, those begun anywhere else in its context.
+ */
+export class PageDownloads {
+    mainFrame;
+    context;
+    popup;
+    #frames = new Set();
+    #listeners;
+    #tracked = new Map();
+    #stopListening;
+    #closed;
+    constructor({ session, mainFrame, browserContextId, popup, onListenerError, closed }) {
+        this.mainFrame = mainFrame;
+        this.context = browserContextId;
+        this.popup = popup;
+        this.#closed = closed;
+        this.#listeners = new Listeners(onListenerError);
+        const source = (method) => ({ method, sessionId: session.id });
+        this.#stopListening = [
+            session.on('Page.frameAttached', (params) => this.#frames.add(readProtocol(frameSchema, params, source('Page.frameAttached')).frameId)),
+            session.on('Page.frameDetached', (params) => this.#frames.delete(readProtocol(frameSchema, params, source('Page.frameDetached')).frameId)),
+            session.on('Page.frameNavigated', (params) => {
+                const { frame } = readProtocol(navigatedSchema, params, source('Page.frameNavigated'));
+                if (frame.parentId !== undefined)
+                    this.#frames.add(frame.id);
+            }),
+        ];
+    }
+    /** Whether the frame is this page's: its main frame, or a frame inside it the page told of. */
+    holds(frameId) {
+        return frameId === this.mainFrame() || this.#frames.has(frameId);
+    }
+    /** Tells `listener` of every download the page is told of from now on. Returns a function that removes it. */
+    onDownload(listener) {
+        return this.#listeners.add(listener);
+    }
+    began({ guid, url, suggestedFilename, startedIn }) {
+        const ended = Promise.withResolvers();
+        const tracked = {
+            received: 0,
+            total: 0,
+            end: ended.resolve,
+            download: {
+                guid,
+                url,
+                suggestedFilename,
+                ...(startedIn === undefined ? {} : { startedIn }),
+                ended: ended.promise,
+                progress: () => ({ receivedBytes: tracked.received, totalBytes: tracked.total }),
+            },
+        };
+        this.#tracked.set(guid, tracked);
+        this.#listeners.emit(tracked.download);
+    }
+    progressed({ guid, receivedBytes, totalBytes, state, filePath }) {
+        const tracked = this.#tracked.get(guid);
+        if (tracked === undefined)
+            return;
+        tracked.received = receivedBytes;
+        tracked.total = totalBytes;
+        if (state === 'inProgress')
+            return;
+        this.#tracked.delete(guid);
+        // A download the browser says it completed, but whose file it does not name, is not one Retest can keep.
+        if (state === 'completed' && filePath !== undefined && isAbsolute(filePath))
+            tracked.end({ state: 'completed', filePath, receivedBytes, totalBytes });
+        else
+            tracked.end({ state: 'canceled', receivedBytes, totalBytes });
+    }
+    /** Stops routing downloads to this page and tells no listener of any more. A download on its way is left as it is. */
+    close() {
+        for (const stop of this.#stopListening)
+            stop();
+        this.#listeners.clear();
+        this.#tracked.clear();
+        this.#closed();
+    }
+}

package/dist/browser/drag.d.ts

@@ -0,0 +1,50 @@
+import type { PendingNavigation } from './actionability.ts';
+import type { CdpSession } from './cdp/session.ts';
+import type { BrowserCommand } from './contract.ts';
+import type { Dispatch } from './dispatch.ts';
+import type { Point } from './input.ts';
+import type { IsolatedWorld } from './isolated-world.ts';
+import type { CommandResult } from '../protocol/commands.ts';
+import type { Failure } from '../protocol/failures.ts';
+import { Deadline } from '../protocol/deadline.ts';
+/** A page as a drag needs it: its session, Retest's world in its main frame, its navigation and its input's cause. */
+export type DragPage = {
+    readonly session: CdpSession;
+    readonly world: IsolatedWorld;
+    readonly touch: boolean;
+    readonly pendingNavigation: () => PendingNavigation | undefined;
+    /** Runs the work that delivers the drag's input, so a navigation it starts is the drag's. */
+    readonly delivering: <T>(work: () => Promise<T>) => Promise<T>;
+};
+type DragCommand = Extract<BrowserCommand, {
+    kind: 'dragTo';
+}>;
+/** Installs Retest's drag listener in each new document, before the page's own scripts run. */
+export declare const dragListenerScript: string;
+/**
+ * Drags the element `command.locator` finds onto the element `command.target` finds. Nothing is sent until both are
+ * ready: the source as for a click, visible, stable, enabled and not covered, and the target visible, stable, in view
+ * and not covered at its centre, both in view together. The press is guarded as a click's is; then the mouse moves in
+ * `steps` from the source's centre to the target's, and is released there. A press and a move that begin an HTML drag
+ * carry it on through drag events, and the drop ends it, with no release, as a person's drop ends one. A target gone
+ * by the time of the drop fails `not_actionable`, after the drag is cancelled, or the mouse released where the moves
+ * ended, and says so; so does an HTML drop another element covers or takes. Every other failure before the press sends
+ * nothing, and one after it leaves no drag held and no button down.
+ *
+ * @example const result = await dragTo(page, { kind: 'dragTo', locator: card, target: column }, deadline, dispatch)
+ */
+export declare function dragTo(page: DragPage, command: DragCommand, deadline: Deadline, dispatch: Dispatch): Promise<CommandResult>;
+/**
+ * The position `fraction` of the way from `from` to `to`, on the straight line between them.
+ *
+ * @example between({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.2) // { x: 20, y: 10 }
+ */
+export declare function between(from: Point, to: Point, fraction: number): Point;
+/**
+ * The failure an engine without drag and drop gives `dragTo()`, naming the engine. Nothing is sent.
+ *
+ * @example dragRefused('Firefox').message // 'dragTo() is not available on Firefox yet. Retest drags on Chrome, Chromium, Edge and Electron.'
+ */
+export declare function dragRefused(engine: string): Failure;
+export {};
+//# sourceMappingURL=drag.d.ts.map

package/dist/browser/drag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drag.d.ts","sourceRoot":"","sources":["../../src/browser/drag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAE5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAA;AAItD,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAuBlD,sHAAsH;AACtH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;IAC5B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,iBAAiB,GAAG,SAAS,CAAA;IAC/D,6FAA6F;IAC7F,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CAC/D,CAAA;AAED,KAAK,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAA;AAsF9D,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,EAAE,MAE5B,CAAA;AAoEL;;;;;;;;;;;GAWG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAcjI;AAsVD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAEvE;AAqGD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD"}