@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/runner/dialogs.js

@@ -0,0 +1,189 @@
+import { smallestBudget } from "../protocol/deadline.js";
+import { dialogTextLimit, unwaitedDialogMessage, withDialogWords } from "../protocol/dialogs.js";
+import { formatSessionId } from "../protocol/evidence.js";
+import { errorMessage, failure, truncateText, withLocation } from "../protocol/failures.js";
+import { NativePageAdapter } from "./native-pool.js";
+/**
+ * The parent's side of a test's JavaScript dialogs. A wait arms the app's page at once, before the action the test runs
+ * next arrives, and gives the test the dialog when it opens, its text redacted, under an id of the attempt's own. An
+ * answer goes to the page that showed the dialog. A dialog nothing waited for is answered by the page, and recorded
+ * here: one that opened while no command ran fails the test, and one that opened during a command fails that command,
+ * in the words `withDialogText` gives it. A dialog the test was given and left open is dismissed as the body settles.
+ * Every dialog that closed is written down as a `dialog` event.
+ */
+export class TestDialogs {
+    #host;
+    #waits = new Map();
+    #given = new Map();
+    #count = 0;
+    constructor(host) {
+        this.#host = host;
+    }
+    /** Hears the dialogs an app's page answers itself. Returns a function that stops listening. */
+    watch(app, page) {
+        return page.onUnwaitedDialog?.((dialog) => this.#unwaited(app, dialog)) ?? (() => undefined);
+    }
+    receive(message) {
+        const { request } = message;
+        if (message.testId !== this.#host.testId || message.attemptId !== this.#host.attemptId)
+            return this.#host.violation('sent a dialog request for an inactive test attempt');
+        if (this.#waits.has(message.id))
+            return this.#host.violation(`sent dialog request ${message.id} again while the first was still waiting`);
+        switch (request.kind) {
+            case 'wait':
+                return this.#wait(message);
+            case 'stop':
+                return this.#stop(message, request.wait);
+            case 'answer':
+                return void this.#answer(message, request).catch((error) => this.#refuse(message.id, failure('setup_failed', `Retest could not answer the dialog: ${errorMessage(error)}`, message.location)));
+        }
+    }
+    /**
+     * Dismisses every dialog the test was given and left open, within `timeoutMs`, so its page answers again and the action
+     * that opened it can end. Each is written down as dismissed by Retest. Nothing is recorded against the test: its own
+     * process names the dialog it left open.
+     */
+    async settle(timeoutMs) {
+        const left = [...this.#given.values()];
+        this.#given.clear();
+        for (const given of left) {
+            const answered = await this.#host.page(given.app)?.answerDialog?.(given.pageId, { accept: false }, Math.max(1, timeoutMs));
+            if (answered?.ok === true)
+                this.#emit({ app: given.app, type: given.type, message: given.message, answer: 'dismissed', by: 'retest', stepId: undefined, location: undefined });
+        }
+    }
+    #wait(message) {
+        const { id, app, location } = message;
+        const refusal = this.#host.refusal();
+        if (refusal !== undefined)
+            return this.#reply(id, { kind: 'failed', failure: withLocation(refusal, location) });
+        const page = this.#host.page(app);
+        if (page === undefined)
+            return this.#host.violation(`sent a dialog request for the app ${JSON.stringify(app)}, which this test does not use`);
+        if (page.armDialog === undefined)
+            return this.#refuse(id, failure('unsupported', noDialogs(app, page), location));
+        const stop = new AbortController();
+        const remaining = this.#host.remainingMs();
+        const arming = page.armDialog(remaining === undefined ? message.timeoutMs : Math.max(1, smallestBudget(message.timeoutMs, remaining)), stop.signal);
+        if (!arming.ok)
+            return this.#refuse(id, withLocation(arming.failure, location));
+        const waiting = { stop, stoppedByTest: false };
+        this.#waits.set(id, waiting);
+        this.#reply(id, { kind: 'armed' });
+        void arming.opened.then((wait) => {
+            this.#waits.delete(id);
+            if (waiting.stoppedByTest)
+                return;
+            // A dialog that opens once the test is over has nobody to answer it, and would hold the page from its screenshot.
+            if (!this.#host.answerable())
+                return void (wait.ok ? this.#dismissLate(app, page, wait.dialog) : undefined);
+            if (!wait.ok)
+                return this.#refuse(id, withLocation(wait.failure, location));
+            const { dialog } = wait;
+            this.#count += 1;
+            const given = `dialog-${this.#count}`;
+            this.#given.set(given, { app, pageId: dialog.id, type: dialog.type, message: dialog.message });
+            const record = { id: given, type: dialog.type, message: this.#host.redact(dialog.message), defaultValue: this.#host.redact(dialog.defaultValue) };
+            this.#reply(id, { kind: 'opened', dialog: record });
+        });
+    }
+    async #dismissLate(app, page, dialog) {
+        const answered = await page.answerDialog?.(dialog.id, { accept: false }, this.#host.timeouts.cleanup);
+        if (answered?.ok === true)
+            this.#emit({ app, type: dialog.type, message: dialog.message, answer: 'dismissed', by: 'retest', stepId: undefined, location: undefined });
+    }
+    // The action the wait was for failed first, and its own failure fails the test; the wait ends without one.
+    #stop(message, wait) {
+        const waiting = this.#waits.get(wait);
+        if (waiting !== undefined) {
+            waiting.stoppedByTest = true;
+            waiting.stop.abort(failure('interrupted', 'The action failed before a dialog opened.'));
+        }
+        this.#reply(message.id, { kind: 'stopped' });
+    }
+    async #answer(message, request) {
+        const { id, location, stepId } = message;
+        const refusal = this.#host.refusal();
+        if (refusal !== undefined)
+            return this.#reply(id, { kind: 'failed', failure: withLocation(refusal, location) });
+        const given = this.#given.get(request.dialog);
+        if (given === undefined || given.app !== message.app)
+            return this.#host.violation(`answered the dialog ${JSON.stringify(request.dialog)}, which Retest did not give it on ${message.app}`);
+        this.#given.delete(request.dialog);
+        const page = this.#host.page(given.app);
+        const timeoutMs = Math.max(1, smallestBudget(message.timeoutMs, this.#host.remainingMs() ?? message.timeoutMs));
+        const reply = { accept: request.accept, ...(request.promptText === undefined ? {} : { promptText: request.promptText }) };
+        const answered = (await page?.answerDialog?.(given.pageId, reply, timeoutMs)) ?? { ok: false, failure: failure('session_lost', 'The page that showed the dialog is gone.') };
+        if (!answered.ok)
+            return this.#refuse(id, withLocation(answered.failure, location));
+        const typed = request.accept && request.promptText !== undefined ? { typed: request.promptText.length } : {};
+        this.#emit({ app: given.app, type: given.type, message: given.message, answer: request.accept ? 'accepted' : 'dismissed', by: 'test', stepId, location, ...typed });
+        if (this.#host.answerable())
+            this.#reply(id, { kind: 'answered' });
+    }
+    // A dialog that opened during a command fails that command; one that opened while none ran fails the test here.
+    // A dialog answered before the test's first command, as an Electron app's alert at start, is written down and fails
+    // nothing: no action of the test opened it, and no change to the test would answer it.
+    #unwaited(app, dialog) {
+        this.#emit({ app, type: dialog.type, message: dialog.message, answer: dialog.answered, by: 'retest', stepId: this.#host.stepId(), location: undefined });
+        if (dialog.during || !this.#host.answerable() || !this.#host.commandsSent())
+            return;
+        const popup = dialog.popup === true;
+        const message = unwaitedDialogMessage({ type: dialog.type, text: this.#host.redact(dialog.message), answered: dialog.answered, popup });
+        this.#host.observe({ ...failure('not_actionable', message), details: { dialog: dialog.type, answered: dialog.answered, ...(popup ? { popup: true } : {}) } });
+    }
+    /** Stops every wait still running, with `reason`, as the test is stopped or ends; none is answered. */
+    stop(reason) {
+        for (const waiting of this.#waits.values()) {
+            waiting.stoppedByTest = true;
+            waiting.stop.abort(reason);
+        }
+    }
+    #emit({ app, type, message, answer, by, stepId, location, typed }) {
+        const { testId, attemptId } = this.#host;
+        const text = truncateText(this.#host.redact(message), dialogTextLimit).text;
+        this.#host.emit({
+            type: 'dialog',
+            testId,
+            attemptId,
+            ...(stepId === undefined ? {} : { stepId }),
+            session: app,
+            sessionId: formatSessionId(attemptId, app),
+            dialog: type,
+            message: text,
+            answer,
+            by,
+            ...(typed === undefined ? {} : { typed }),
+            ...(location === undefined ? {} : { location }),
+        });
+    }
+    // A failure the parent gave a wait or an answer is its own, as an inbox read's is.
+    #refuse(id, problem) {
+        if (!this.#host.answerable())
+            return;
+        this.#host.observe(problem);
+        this.#reply(id, { kind: 'failed', failure: problem });
+    }
+    #reply(id, answer) {
+        this.#host.send({ type: 'dialog-result', id, answer });
+    }
+}
+/**
+ * A command's answer, with a dialog the page answered while the command ran named in words: the page gives the
+ * dialog's text apart, as the page showed it, and only the parent can hide the run's values in it before quoting it.
+ * Any other answer is given back as it is.
+ *
+ * @example withDialogText(result, (text) => redactor.redact(text))
+ */
+export function withDialogText(result, redact) {
+    if (result.ok)
+        return result;
+    const failure = withDialogWords(result.failure, redact);
+    return failure === result.failure ? result : { ok: false, failure };
+}
+// A native app shows no JavaScript dialog; any other page without dialogs belongs to an engine that refuses them.
+function noDialogs(app, page) {
+    if (page instanceof NativePageAdapter)
+        return `${app} is a native app, which shows no JavaScript dialog. Answer its alerts with page.alert.`;
+    return `The page of ${app} cannot hand its dialogs to a test.`;
+}

package/dist/runner/files.d.ts

@@ -0,0 +1,79 @@
+import type { FilesCapability } from '../browser/contract.ts';
+import type { EventBody } from '../protocol/events.ts';
+import type { Failure, SourceLocation } from '../protocol/failures.ts';
+import type { FilesAnswer, InputFileRecord } from '../protocol/files.ts';
+import type { Redactor } from './redactor.ts';
+/** The folder of a run where Retest writes the files a test gives an input by content, while their test runs. */
+export declare const uploadsFolder = "uploads";
+/**
+ * One app's page as the attempt's files see it: its file pickers and downloads, when it has them, where it runs, for a
+ * refusal that names it, such as `on Firefox` or `in an Electron app`, its session, and, when it saves downloads, the
+ * folder they go to, absolute and as a reference in the run folder.
+ */
+export type FilesPage = {
+    readonly files: FilesCapability | undefined;
+    readonly where: string;
+    readonly sessionId: string;
+    readonly downloads?: {
+        readonly folder: string;
+        readonly reference: string;
+    } | undefined;
+};
+export type AttemptFilesOptions = {
+    readonly pages: ReadonlyMap<string, FilesPage>;
+    readonly runFolder: string;
+    readonly testId: string;
+    readonly attemptId: string;
+    readonly redactor?: Redactor | undefined;
+    readonly emit: (body: EventBody) => void;
+};
+/** How long a request may wait, the signal that stops it, and the step and place of the call that made it. */
+export type FilesBudget = {
+    readonly timeoutMs: number;
+    readonly signal: AbortSignal;
+    readonly stepId?: string | undefined;
+    readonly location?: SourceLocation | undefined;
+};
+/** The files of an input command, as the page takes them: absolute paths, and the type the test named for each, or null. */
+export type ResolvedFiles = {
+    ok: true;
+    paths: string[];
+    mimeTypes: (string | null)[];
+} | {
+    ok: false;
+    failure: Failure;
+};
+/**
+ * One attempt's files: the files a test gives an input, checked and, when given by content, written to a folder of the
+ * run's own; the file pickers a test waits for; and every download an app's browser context makes, saved under the
+ * name the page suggested in its session's downloads folder, and written down once it ends, whether or not the test
+ * waited for it. A download that holds the value of a secret is removed rather than kept.
+ */
+export declare class AttemptFiles {
+    #private;
+    constructor(options: AttemptFilesOptions);
+    /**
+     * The paths a page gives an input for the files a test named: each path read against the folder of the file that
+     * made the call, and each file given by content written to a folder of the run's own, named as the test named it.
+     * A path with no file at it fails `usage`, naming the path.
+     */
+    stage(files: readonly InputFileRecord[], method: string): ResolvedFiles;
+    /** Waits for the next file picker the app's page opens, within the budget, and answers with it. */
+    chooser(app: string, budget: FilesBudget): Promise<FilesAnswer>;
+    /** Waits for the next download the app's page begins, within the budget, and answers with it. */
+    download(app: string, budget: FilesBudget): Promise<FilesAnswer>;
+    /** Waits for a download the test was given to be saved, within the budget, and answers with its path and size. */
+    saved(id: string, budget: FilesBudget): Promise<FilesAnswer>;
+    /**
+     * Ends the attempt's files: each download still on its way is written down as unfinished, no later one is told of,
+     * and the files written for inputs are removed with their folder.
+     */
+    close(): void;
+}
+/**
+ * A name in `folder` no file holds yet: `name` itself, or with `-2`, `-3` and so on before its extension.
+ *
+ * @example freeName('/run/downloads', 'tasks.csv') // 'tasks-2.csv' when tasks.csv is there
+ */
+export declare function freeName(folder: string, name: string): string;
+//# sourceMappingURL=files.d.ts.map

package/dist/runner/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/runner/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAe,eAAe,EAAgB,MAAM,wBAAwB,CAAA;AACxF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACtE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACxE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAU7C,iHAAiH;AACjH,eAAO,MAAM,aAAa,YAAY,CAAA;AAOtC;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,CAAA;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;CACzF,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAA;CACzC,CAAA;AAED,8GAA8G;AAC9G,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CAAE,CAAA;AAE5K,4HAA4H;AAC5H,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAA;AAezH;;;;;GAKG;AACH,qBAAa,YAAY;;gBASX,OAAO,EAAE,mBAAmB;IAQxC;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa;IA0BvE,mGAAmG;IAC7F,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAarE,iGAAiG;IAC3F,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBtE,kHAAkH;IAC5G,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAYlE;;;OAGG;IACH,KAAK,IAAI,IAAI;CAmHd;AASD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAS7D"}

package/dist/runner/files.js

@@ -0,0 +1,312 @@
+import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, rmdirSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, extname, join, resolve } from 'node:path';
+import { filesRefused } from "../browser/file-chooser.js";
+import { originAndPath } from "../browser/page-url.js";
+import { errorMessage, failure, failureSchema } from "../protocol/failures.js";
+import { parse } from "../protocol/schema.js";
+import { downloadFileName } from "../store/artifacts.js";
+import { bounded } from "./bounded.js";
+/** The folder of a run where Retest writes the files a test gives an input by content, while their test runs. */
+export const uploadsFolder = 'uploads';
+// A saved download is read for secrets a piece at a time, each piece beginning with the end of the one before, so a
+// value that a piece's edge cuts is still read whole, up to this many characters long.
+const pieceBytes = 8 * 1024 * 1024;
+const pieceOverlap = 64 * 1024;
+/**
+ * One attempt's files: the files a test gives an input, checked and, when given by content, written to a folder of the
+ * run's own; the file pickers a test waits for; and every download an app's browser context makes, saved under the
+ * name the page suggested in its session's downloads folder, and written down once it ends, whether or not the test
+ * waited for it. A download that holds the value of a secret is removed rather than kept.
+ */
+export class AttemptFiles {
+    #options;
+    #kept = new Map();
+    // What a `page.download()` on an app waits for: the next download that app begins.
+    #waiting = new Map();
+    #stopListening = [];
+    #staged = 0;
+    #closed = false;
+    constructor(options) {
+        this.#options = options;
+        for (const [app, page] of options.pages) {
+            const stop = page.downloads === undefined ? undefined : page.files?.onDownload?.((download) => this.#began(app, page, download));
+            if (stop !== undefined)
+                this.#stopListening.push(stop);
+        }
+    }
+    /**
+     * The paths a page gives an input for the files a test named: each path read against the folder of the file that
+     * made the call, and each file given by content written to a folder of the run's own, named as the test named it.
+     * A path with no file at it fails `usage`, naming the path.
+     */
+    stage(files, method) {
+        const paths = [];
+        const mimeTypes = [];
+        for (const file of files) {
+            if ('path' in file) {
+                const path = resolve(file.folder, file.path);
+                const problem = fileProblem(path);
+                if (problem !== undefined)
+                    return { ok: false, failure: { ...failure('usage', `${method}() ${problem}`), details: { path, inputSent: false } } };
+                paths.push(path);
+                mimeTypes.push(null);
+                continue;
+            }
+            this.#staged += 1;
+            const folder = join(this.#options.runFolder, uploadsFolder, this.#options.attemptId, String(this.#staged));
+            try {
+                mkdirSync(folder, { recursive: true });
+                writeFileSync(join(folder, file.name), Buffer.from(file.base64, 'base64'));
+            }
+            catch (error) {
+                return { ok: false, failure: failure('setup_failed', `Retest could not write ${file.name} for ${method}(): ${errorMessage(error)}`) };
+            }
+            paths.push(join(folder, file.name));
+            mimeTypes.push(file.mimeType ?? null);
+        }
+        return { ok: true, paths, mimeTypes };
+    }
+    /** Waits for the next file picker the app's page opens, within the budget, and answers with it. */
+    async chooser(app, budget) {
+        const page = this.#options.pages.get(app);
+        if (page?.files === undefined)
+            return refused(filesRefused('chooser', page?.where ?? 'on this app'));
+        const arm = page.files.armFileChooser();
+        const opened = await bounded(arm.opened, budget.timeoutMs, aborted(budget.signal));
+        if (opened.status === 'done')
+            return { ok: true, kind: 'chooser', chooser: opened.value.id, multiple: opened.value.multiple };
+        arm.release();
+        if (opened.status === 'failed')
+            return refused(failureOf(opened.error));
+        if (opened.status === 'stopped')
+            return refused(stoppedBy(budget.signal, 'Retest stopped waiting for a file picker.'));
+        const message = `No file picker opened within ${budget.timeoutMs} ms of page.fileChooser(). Check that its action opens one, as a click on an upload button does.`;
+        return refused({ ...failure('timeout', message), details: { timeoutMs: budget.timeoutMs } });
+    }
+    /** Waits for the next download the app's page begins, within the budget, and answers with it. */
+    async download(app, budget) {
+        const page = this.#options.pages.get(app);
+        if (page?.files?.onDownload === undefined || page.downloads === undefined)
+            return refused(filesRefused('download', page?.where ?? 'on this app'));
+        if (this.#waiting.has(app))
+            return refused(failure('usage', 'page.download() is already waiting for a download on this app. Await it before you wait for the next.'));
+        const began = Promise.withResolvers();
+        this.#waiting.set(app, began.resolve);
+        const waited = await bounded(began.promise, budget.timeoutMs, aborted(budget.signal));
+        if (this.#waiting.get(app) === began.resolve)
+            this.#waiting.delete(app);
+        if (waited.status === 'done') {
+            const kept = waited.value;
+            kept.given = { stepId: budget.stepId, location: budget.location };
+            return { ok: true, kind: 'download', download: kept.id, suggestedFilename: this.#redact(kept.download.suggestedFilename) };
+        }
+        if (waited.status === 'stopped')
+            return refused(stoppedBy(budget.signal, 'Retest stopped waiting for a download.'));
+        const message = `No download began within ${budget.timeoutMs} ms of page.download(). Check that its action starts one, as a link to a file does.`;
+        return refused({ ...failure('timeout', message), details: { timeoutMs: budget.timeoutMs } });
+    }
+    /** Waits for a download the test was given to be saved, within the budget, and answers with its path and size. */
+    async saved(id, budget) {
+        const kept = this.#kept.get(id);
+        if (kept?.given === undefined)
+            return refused(failure('usage', 'This download is not one page.download() gave this test, so Retest has no file for it.'));
+        const saved = await bounded(kept.saved, budget.timeoutMs, aborted(budget.signal));
+        if (saved.status === 'done')
+            return saved.value.ok ? { ok: true, kind: 'saved', path: saved.value.path, size: saved.value.size } : refused(saved.value.failure);
+        if (saved.status === 'failed')
+            return refused(failureOf(saved.error));
+        if (saved.status === 'stopped')
+            return refused(stoppedBy(budget.signal, 'Retest stopped waiting for the download to be saved.'));
+        const name = this.#redact(kept.download.suggestedFilename);
+        const message = `The download of ${name} was not saved within ${budget.timeoutMs} ms: ${describeProgress(kept.download.progress())} had arrived.`;
+        return refused({ ...failure('timeout', message), details: { timeoutMs: budget.timeoutMs } });
+    }
+    /**
+     * Ends the attempt's files: each download still on its way is written down as unfinished, no later one is told of,
+     * and the files written for inputs are removed with their folder.
+     */
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const stop of this.#stopListening)
+            stop();
+        for (const kept of this.#kept.values()) {
+            if (kept.done)
+                continue;
+            kept.done = true;
+            this.#write(kept, { state: 'unfinished', ...kept.download.progress() });
+        }
+        rmSync(join(this.#options.runFolder, uploadsFolder, this.#options.attemptId), { recursive: true, force: true });
+        removeQuietly(join(this.#options.runFolder, uploadsFolder), rmdirSync);
+    }
+    // A `page.download()` takes a download the page, a frame inside it or a page it opened began, never one another page of
+    // its context began.
+    #began(app, page, download) {
+        if (this.#closed)
+            return;
+        const id = `download-${this.#kept.size + 1}`;
+        const saved = Promise.withResolvers();
+        const kept = { id, app, page, download, saved: saved.promise, done: false };
+        this.#kept.set(id, kept);
+        void download.ended.then((end) => saved.resolve(this.#ended(kept, end)));
+        const waiting = this.#waiting.get(app);
+        if (waiting === undefined || download.startedIn === 'other')
+            return;
+        this.#waiting.delete(app);
+        waiting(kept);
+    }
+    // A completed download takes the name the page suggested, made safe for a file name, with a number before its
+    // extension when the folder already holds one by that name. One that holds the value of a secret is removed, even once
+    // its test has ended, since a secret never reaches a file of the run. A cancelled one leaves no file of its own behind.
+    #ended(kept, end) {
+        const folder = kept.page.downloads;
+        const name = this.#redact(kept.download.suggestedFilename);
+        if (end.state === 'completed' && this.#holdsSecret(end.filePath)) {
+            removeQuietly(end.filePath);
+            const message = `Retest did not keep the download of ${name}: it holds the value of a secret, and a secret never reaches a file of the run. Retest removed the file.`;
+            const withheld = { ...failure('unsupported', message), details: { download: name } };
+            if (!kept.done)
+                this.#write(kept, { state: 'withheld', size: end.receivedBytes, failure: withheld });
+            kept.done = true;
+            return { ok: false, failure: withheld };
+        }
+        if (folder === undefined || kept.done)
+            return { ok: false, failure: failure('interrupted', `The test ended before the download of ${name} was saved.`) };
+        kept.done = true;
+        if (end.state === 'canceled') {
+            removeQuietly(join(folder.folder, `${kept.download.guid}.crdownload`));
+            const message = `The browser stopped the download of ${name} after ${describeProgress(end)} had arrived, and gives no reason. Retest saved nothing.`;
+            const stopped = { ...failure('not_actionable', message), details: { download: name, receivedBytes: end.receivedBytes, totalBytes: end.totalBytes } };
+            this.#write(kept, { state: 'canceled', receivedBytes: end.receivedBytes, totalBytes: end.totalBytes, failure: stopped });
+            return { ok: false, failure: stopped };
+        }
+        if (resolve(dirname(end.filePath)) !== resolve(folder.folder)) {
+            const outside = failure('setup_failed', `The browser saved the download of ${name} outside its folder, so Retest did not keep it.`);
+            this.#write(kept, { state: 'canceled', receivedBytes: end.receivedBytes, totalBytes: end.totalBytes, failure: outside });
+            return { ok: false, failure: outside };
+        }
+        try {
+            const file = freeName(folder.folder, downloadFileName(name));
+            renameSync(end.filePath, join(folder.folder, file));
+            const { size } = statSync(join(folder.folder, file));
+            this.#write(kept, { state: 'completed', path: `${folder.reference}/${file}`, size });
+            return { ok: true, path: join(folder.folder, file), size };
+        }
+        catch (error) {
+            const lost = failure('setup_failed', `Retest could not keep the download of ${name}: ${errorMessage(error)}`);
+            this.#write(kept, { state: 'canceled', receivedBytes: end.receivedBytes, totalBytes: end.totalBytes, failure: lost });
+            return { ok: false, failure: lost };
+        }
+    }
+    #write(kept, ending) {
+        const { testId, attemptId } = this.#options;
+        const given = kept.given === undefined ? {} : { awaited: true, ...(kept.given.stepId === undefined ? {} : { stepId: kept.given.stepId }), ...(kept.given.location === undefined ? {} : { location: kept.given.location }) };
+        this.#options.emit({
+            type: 'download',
+            testId,
+            attemptId,
+            session: kept.app,
+            sessionId: kept.page.sessionId,
+            suggestedFilename: this.#redact(kept.download.suggestedFilename),
+            url: this.#redact(downloadAddress(kept.download.url)),
+            ...(kept.download.startedIn === undefined ? {} : { startedIn: kept.download.startedIn }),
+            ...ending,
+            ...given,
+        });
+    }
+    #redact(text) {
+        return this.#options.redactor?.redact(text) ?? text;
+    }
+    // Whether the file holds a value the run hides, read as text in every form the redactor knows it. A run that hides no
+    // value reads nothing.
+    #holdsSecret(path) {
+        const { redactor } = this.#options;
+        if (redactor === undefined || !redactor.active)
+            return false;
+        let file;
+        try {
+            file = openSync(path, 'r');
+        }
+        catch {
+            return false;
+        }
+        try {
+            const piece = Buffer.alloc(pieceBytes);
+            let carried = '';
+            for (;;) {
+                const read = readSync(file, piece, 0, pieceBytes, null);
+                if (read === 0)
+                    return false;
+                const text = carried + piece.toString('utf8', 0, read);
+                if (redactor.redact(text) !== text)
+                    return true;
+                carried = text.slice(-pieceOverlap);
+            }
+        }
+        finally {
+            closeSync(file);
+        }
+    }
+}
+/**
+ * A name in `folder` no file holds yet: `name` itself, or with `-2`, `-3` and so on before its extension.
+ *
+ * @example freeName('/run/downloads', 'tasks.csv') // 'tasks-2.csv' when tasks.csv is there
+ */
+export function freeName(folder, name) {
+    if (!existsSync(join(folder, name)))
+        return name;
+    const extension = extname(name);
+    const stem = extension === '' || extension === name ? name : name.slice(0, -extension.length);
+    const suffix = extension === name ? '' : extension;
+    for (let number = 2;; number += 1) {
+        const candidate = `${stem}-${number}${suffix}`;
+        if (!existsSync(join(folder, candidate)))
+            return candidate;
+    }
+}
+// Where a download came from, as an address is recorded: its origin and path, never its query, which can carry what the
+// page was given. An address with no host, such as a blob's or a data address, keeps its scheme alone.
+function downloadAddress(url) {
+    const parsed = URL.parse(url);
+    return parsed === null ? 'an address Retest cannot read' : originAndPath(parsed);
+}
+function describeProgress({ receivedBytes, totalBytes }) {
+    return totalBytes > 0 ? `${receivedBytes} of ${totalBytes} bytes` : `${receivedBytes} bytes`;
+}
+function fileProblem(path) {
+    try {
+        const stats = statSync(path);
+        return stats.isFile() ? undefined : `received ${path}, which is not a file.`;
+    }
+    catch {
+        return `found no file at ${path}.`;
+    }
+}
+// What is gone already, or a folder another attempt still writes in, is left as it is.
+function removeQuietly(path, remove = unlinkSync) {
+    try {
+        remove(path);
+    }
+    catch {
+        // The browser removes what it left of some downloads itself, and an attempt that still runs keeps its files.
+    }
+}
+function refused(problem) {
+    return { ok: false, failure: problem };
+}
+// A browser's refusal of an arm carries its failure; anything else thrown is the browser call failing.
+function failureOf(error) {
+    const carried = typeof error === 'object' && error !== null && 'failure' in error ? parse(failureSchema, error.failure) : undefined;
+    return carried?.ok === true ? carried.value : failure('session_lost', `The browser call failed: ${errorMessage(error)}`);
+}
+function stoppedBy(signal, fallback) {
+    const parsed = parse(failureSchema, signal.reason);
+    return parsed.ok ? parsed.value : failure('interrupted', fallback);
+}
+function aborted(signal) {
+    if (signal.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => signal.addEventListener('abort', () => resolve(), { once: true }));
+}

package/dist/runner/inbox-links.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A message's link as Retest reads it: the address it parsed, and the parts of it that read as tokens, each as the
+ * address writes it and decoded, with no repeats. A link with any such part carries a token.
+ */
+export type ReadLink = {
+    readonly url: URL;
+    readonly tokens: readonly string[];
+};
+/**
+ * Reads a link from a message, or undefined when its address is not an http or https URL. A password in the address is
+ * a token. A part reads as a token when it is one of the message's codes; when it is a query parameter, or a parameter of a fragment written as a query,
+ * whose name speaks of a credential; or when it reads as one as diagnostics read a path segment: 16 letters and digits
+ * or more, 12 digits or more, or a JSON Web Token's shape, and not a file name, a version or a date. That rule applies
+ * to each path segment, each query value and the fragment.
+ *
+ * @example readLink('https://app.test/verify/9f8e7d6c5b4a39281706f5e4?utm=mail', [])?.tokens // ['9f8e7d6c5b4a39281706f5e4']
+ */
+export declare function readLink(address: string, codes: readonly string[]): ReadLink | undefined;
+//# sourceMappingURL=inbox-links.d.ts.map

package/dist/runner/inbox-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox-links.d.ts","sourceRoot":"","sources":["../../src/runner/inbox-links.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAA;AAMhF;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,QAAQ,GAAG,SAAS,CAexF"}