@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/api/dialog.js

@@ -0,0 +1,78 @@
+import { readCallOptions } from "./call-options.js";
+import { formatValue } from "./format-value.js";
+import { misuse } from "./misuse.js";
+import { isThenable } from "./operation.js";
+/** A dialog the parent handed to the test, which the test answers through the page that showed it. */
+export class AppDialog {
+    type;
+    message;
+    defaultValue;
+    #run;
+    #app;
+    #id;
+    #acted;
+    #answered;
+    constructor(run, app, record, acted) {
+        this.type = record.type;
+        this.message = record.message;
+        this.defaultValue = record.defaultValue;
+        this.#run = run;
+        this.#app = app;
+        this.#id = record.id;
+        this.#acted = acted;
+    }
+    accept(promptText) {
+        const location = this.#run.location();
+        if (promptText !== undefined && typeof promptText !== 'string')
+            throw misuse(`accept() takes the text a prompt dialog answers with, received ${formatValue(promptText)}.`, this.#run);
+        if (promptText !== undefined && this.type !== 'prompt')
+            throw misuse(`accept() takes text only for a prompt dialog, and this is ${article(this.type)} ${this.type} dialog.`, this.#run);
+        return this.#answer({ accept: true, promptText, label: 'dialog.accept()', how: 'accepted', location });
+    }
+    dismiss() {
+        return this.#answer({ accept: false, promptText: undefined, label: 'dialog.dismiss()', how: 'dismissed', location: this.#run.location() });
+    }
+    #answer({ accept, promptText, label, how, location }) {
+        const answered = this.#answered;
+        if (answered !== undefined)
+            throw misuse(`This ${this.type} dialog was already ${answered.how} on ${this.#run.describeLine(answered.location)}. Answer each dialog once.`, this.#run);
+        this.#answered = { how, location };
+        return this.#run.answerDialog({ app: this.#app, dialog: this.#id, accept, promptText, label, location, acted: this.#acted });
+    }
+}
+/**
+ * Arms an app's page for its next dialog, runs `action`, and resolves with the dialog as soon as it opens, while the
+ * action still waits on it. `options` may shorten the wait, as `{ timeout }` does an action's.
+ *
+ * @example const dialog = await waitForDialog({ run, app: 'web' }, () => page.getByRole('button', { name: 'Delete' }).click())
+ */
+export function waitForDialog({ run, app }, action, options) {
+    const location = run.location();
+    const read = readOpening('dialog', run, action, options);
+    return run.waitForDialog({ app, label: 'page.dialog()', location, timeoutMs: read.timeoutMs, action: read.action }, (record, acted) => new AppDialog(run, app, record, acted));
+}
+/**
+ * Reads the action and the options `page.dialog()` or `page.popup()` was given, as a JavaScript caller may have passed
+ * them any way it liked. The action must be a function, and what it returns must be a promise, the action's own.
+ *
+ * @example readOpening('popup', run, () => page.getByRole('link', { name: 'Terms' }).click(), undefined).timeoutMs // undefined
+ */
+export function readOpening(kind, run, action, options) {
+    const call = `page.${kind}()`;
+    const example = kind === 'dialog' ? "() => page.getByRole('button', { name: 'Delete' }).click()" : "() => page.getByRole('link', { name: 'Terms' }).click()";
+    if (typeof action !== 'function')
+        throw misuse(`${call} takes a function that runs the action, such as ${example}, received ${formatValue(action)}.`, run);
+    const read = readCallOptions(kind, options);
+    if (!read.ok)
+        throw misuse(read.problem, run);
+    const returning = async () => {
+        const returned = action();
+        if (!isThenable(returned))
+            throw misuse(`${call} runs its function and waits for the promise it returns, and it returned ${formatValue(returned)}. Return the action, as in ${example}.`, run);
+        return returned;
+    };
+    return { action: returning, timeoutMs: read.timeoutMs };
+}
+function article(word) {
+    return /^[aeiou]/.test(word) ? 'an' : 'a';
+}

package/dist/api/drag.d.ts

@@ -0,0 +1,32 @@
+import type { CallOptions } from './call-options.ts';
+/**
+ * Options a drag takes: `steps`, how many positions the mouse moves through on its way to the target, 5 when absent and
+ * at most 100, and the `timeout` every action takes.
+ */
+export type DragOptions = CallOptions & {
+    readonly steps?: number | undefined;
+};
+/**
+ * A drag's options as the command takes them: its steps when given, and the timeout as the caller passed it, which the
+ * action reads as every action reads its own.
+ */
+export type ReadDragOptions = {
+    readonly ok: true;
+    readonly steps: {
+        steps?: number;
+    };
+    readonly call: {
+        readonly timeout: unknown;
+    } | undefined;
+} | {
+    readonly ok: false;
+    readonly problem: string;
+};
+/**
+ * Reads the options a JavaScript caller may have passed `dragTo` any way it liked, and says what is wrong as a sentence.
+ * `timeout` is left for the action to read, as every action reads its own.
+ *
+ * @example readDragOptions({ steps: 10, timeout: 2000 }) // { ok: true, steps: { steps: 10 }, call: { timeout: 2000 } }
+ */
+export declare function readDragOptions(options: unknown): ReadDragOptions;
+//# sourceMappingURL=drag.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"drag.d.ts","sourceRoot":"","sources":["../../src/api/drag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAKpD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAE/E;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpM;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,CAWjE"}

package/dist/api/drag.js

@@ -0,0 +1,26 @@
+import { dragProblem } from "../protocol/drag.js";
+import { isPlainObject } from "../protocol/schema.js";
+import { formatValue } from "./format-value.js";
+/**
+ * Reads the options a JavaScript caller may have passed `dragTo` any way it liked, and says what is wrong as a sentence.
+ * `timeout` is left for the action to read, as every action reads its own.
+ *
+ * @example readDragOptions({ steps: 10, timeout: 2000 }) // { ok: true, steps: { steps: 10 }, call: { timeout: 2000 } }
+ */
+export function readDragOptions(options) {
+    if (options === undefined)
+        return { ok: true, steps: {}, call: undefined };
+    if (!isPlainObject(options))
+        return { ok: false, problem: `dragTo() takes options such as { steps: 10, timeout: 2000 }, received ${formatValue(options)}.` };
+    const given = Object.entries(options).filter(([, value]) => value !== undefined);
+    const unknown = given.find(([key]) => key !== 'steps' && key !== 'timeout');
+    if (unknown !== undefined)
+        return { ok: false, problem: `Unknown dragTo() option ${JSON.stringify(unknown[0])}. Its options are steps and timeout.` };
+    const { steps, timeout } = Object.fromEntries(given);
+    if (steps !== undefined && typeof steps !== 'number')
+        return { ok: false, problem: `dragTo() takes steps as a whole number from 1 to 100, received ${formatValue(steps)}.` };
+    const problem = dragProblem({ steps });
+    if (problem !== undefined)
+        return { ok: false, problem: problem.message };
+    return { ok: true, steps: steps === undefined ? {} : { steps }, call: timeout === undefined ? undefined : { timeout } };
+}

package/dist/api/files.d.ts

@@ -0,0 +1,49 @@
+import type { InputFileRecord } from '../protocol/files.ts';
+import type { LocatorRecipe } from '../protocol/locator.ts';
+import type { Download, FileChooser } from './page.ts';
+import type { TestRun } from './test-run.ts';
+/** The test, app and recipe behind a locator, as giving files to it needs them. */
+type InputTarget = {
+    readonly run: TestRun;
+    readonly app: string;
+    readonly recipe: LocatorRecipe;
+};
+/** The test and app behind a page. */
+type PageTarget = {
+    readonly run: TestRun;
+    readonly app: string;
+};
+/**
+ * Gives the one file input a locator finds the files: the input that `setInputFiles` is called on.
+ *
+ * @example await setInputFiles(target, './report.pdf', undefined)
+ */
+export declare function setInputFiles({ run, app, recipe }: InputTarget, files: unknown, options: unknown): Promise<void>;
+/**
+ * Arms the app's page for the next file picker it opens, runs `action`, and gives the picker that opened. The wait for
+ * it starts before the action and lasts the action budget, or a shorter `{ timeout }`.
+ *
+ * @example const chooser = await fileChooser(page, () => button.click(), undefined)
+ */
+export declare function fileChooser(page: PageTarget, action: unknown, options: unknown): Promise<FileChooser>;
+/**
+ * Arms the app's page for the next download it begins, runs `action`, and gives the download that began. The wait for
+ * it starts before the action and lasts the action budget, or a shorter `{ timeout }`.
+ *
+ * @example const download = await download(page, () => link.click(), undefined)
+ */
+export declare function download(page: PageTarget, action: unknown, options: unknown): Promise<Download>;
+/** The files a test gave, as the parent takes them, and whether it gave a list. */
+type ReadFiles = {
+    files: InputFileRecord[];
+    list: boolean;
+};
+/**
+ * Reads the files a JavaScript caller may have passed any way it liked, and says what is wrong as a sentence. A path is
+ * kept as the test wrote it, with the folder it is read against.
+ *
+ * @example readInputFiles('./report.pdf', '/work/tests', 'setInputFiles') // { files: [{ path: './report.pdf', folder: '/work/tests' }], list: false }
+ */
+export declare function readInputFiles(value: unknown, folder: string, method: string): ReadFiles | string;
+export {};
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/api/files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAc,MAAM,WAAW,CAAA;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAU5C,mFAAmF;AACnF,KAAK,WAAW,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAElG,sCAAsC;AACtC,KAAK,UAAU,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAA;AAkEjE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAKhH;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC,CAUrG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAU/F;AAQD,mFAAmF;AACnF,KAAK,SAAS,GAAG;IAAE,KAAK,EAAE,eAAe,EAAE,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAA;AAE5D;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAejG"}

package/dist/api/files.js

@@ -0,0 +1,168 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { errorMessage, failure } from "../protocol/failures.js";
+import { inputFilesProblem } from "../protocol/files.js";
+import { isArray, isPlainObject } from "../protocol/schema.js";
+import { readCallOptions } from "./call-options.js";
+import { formatValue } from "./format-value.js";
+import { misuse } from "./misuse.js";
+/** A file picker the parent caught for the test, whose input the test gives files through the page that opened it. */
+class AppFileChooser {
+    multiple;
+    #page;
+    #chooser;
+    constructor(page, chooser, multiple) {
+        this.#page = page;
+        this.#chooser = chooser;
+        this.multiple = multiple;
+    }
+    setFiles(files, options) {
+        const { run, app } = this.#page;
+        const location = run.location();
+        const read = readInputFiles(files, run.callerFolder(location), 'setFiles');
+        if (typeof read === 'string')
+            throw misuse(read, run);
+        return run.action(app, { kind: 'setChooserFiles', chooser: this.#chooser, files: read.files, ...(read.list ? { list: true } : {}) }, location, options);
+    }
+}
+/** A download the parent caught for the test, whose saved file the test asks the parent for. */
+class AppDownload {
+    suggestedFilename;
+    #page;
+    #download;
+    constructor(page, download, suggestedFilename) {
+        this.#page = page;
+        this.#download = download;
+        this.suggestedFilename = suggestedFilename;
+    }
+    path(options) {
+        return this.#saved('download.path()', 'path', options, async (path) => path);
+    }
+    saveAs(path, options) {
+        const { run } = this.#page;
+        if (typeof path !== 'string' || path === '')
+            throw misuse(`download.saveAs() takes the path to copy the file to, received ${formatValue(path)}.`, run);
+        const target = resolve(run.callerFolder(run.location()), path);
+        return this.#saved('download.saveAs()', 'saveAs', options, async (saved) => {
+            try {
+                await mkdir(dirname(target), { recursive: true });
+                await copyFile(saved, target);
+            }
+            catch (error) {
+                throw run.fail(failure('usage', `download.saveAs() could not copy ${this.suggestedFilename} to ${target}: ${errorMessage(error)}`, run.location()));
+            }
+        });
+    }
+    #saved(label, method, options, then) {
+        const { run } = this.#page;
+        const location = run.location();
+        const read = readCallOptions(method, options);
+        if (!read.ok)
+            throw misuse(read.problem, run);
+        const timeoutMs = Math.min(read.timeoutMs ?? run.timeouts.navigation, run.timeouts.navigation);
+        return run.awaitFiles({ label, request: { kind: 'saved', download: this.#download }, location, timeoutMs }, (answer) => {
+            if (answer.kind !== 'saved')
+                throw new Error(`Retest answered a wait for a saved download with ${answer.kind}`);
+            return then(answer.path);
+        });
+    }
+}
+/**
+ * Gives the one file input a locator finds the files: the input that `setInputFiles` is called on.
+ *
+ * @example await setInputFiles(target, './report.pdf', undefined)
+ */
+export function setInputFiles({ run, app, recipe }, files, options) {
+    const location = run.location();
+    const read = readInputFiles(files, run.callerFolder(location), 'setInputFiles');
+    if (typeof read === 'string')
+        throw misuse(read, run);
+    return run.action(app, { kind: 'setInputFiles', locator: recipe, files: read.files, ...(read.list ? { list: true } : {}) }, location, options);
+}
+/**
+ * Arms the app's page for the next file picker it opens, runs `action`, and gives the picker that opened. The wait for
+ * it starts before the action and lasts the action budget, or a shorter `{ timeout }`.
+ *
+ * @example const chooser = await fileChooser(page, () => button.click(), undefined)
+ */
+export function fileChooser(page, action, options) {
+    const { run } = page;
+    const location = run.location();
+    if (typeof action !== 'function')
+        throw misuse(`page.fileChooser() takes the action that opens the picker, such as () => upload.click(), received ${formatValue(action)}.`, run);
+    const timeoutMs = actionBudget(run, 'fileChooser', options);
+    const request = { kind: 'chooser', app: page.app };
+    return run.awaitFiles({ label: 'page.fileChooser()', request, location, timeoutMs }, (answer) => {
+        if (answer.kind !== 'chooser')
+            throw new Error(`Retest answered a wait for a file picker with ${answer.kind}`);
+        return new AppFileChooser(page, answer.chooser, answer.multiple);
+    }, () => action());
+}
+/**
+ * Arms the app's page for the next download it begins, runs `action`, and gives the download that began. The wait for
+ * it starts before the action and lasts the action budget, or a shorter `{ timeout }`.
+ *
+ * @example const download = await download(page, () => link.click(), undefined)
+ */
+export function download(page, action, options) {
+    const { run } = page;
+    const location = run.location();
+    if (typeof action !== 'function')
+        throw misuse(`page.download() takes the action that starts the download, such as () => link.click(), received ${formatValue(action)}.`, run);
+    const timeoutMs = actionBudget(run, 'download', options);
+    const request = { kind: 'download', app: page.app };
+    return run.awaitFiles({ label: 'page.download()', request, location, timeoutMs }, (answer) => {
+        if (answer.kind !== 'download')
+            throw new Error(`Retest answered a wait for a download with ${answer.kind}`);
+        return new AppDownload(page, answer.download, answer.suggestedFilename);
+    }, () => action());
+}
+function actionBudget(run, method, options) {
+    const read = readCallOptions(method, options);
+    if (!read.ok)
+        throw misuse(read.problem, run);
+    return Math.min(read.timeoutMs ?? run.timeouts.action, run.timeouts.action);
+}
+/**
+ * Reads the files a JavaScript caller may have passed any way it liked, and says what is wrong as a sentence. A path is
+ * kept as the test wrote it, with the folder it is read against.
+ *
+ * @example readInputFiles('./report.pdf', '/work/tests', 'setInputFiles') // { files: [{ path: './report.pdf', folder: '/work/tests' }], list: false }
+ */
+export function readInputFiles(value, folder, method) {
+    const list = isArray(value);
+    const given = isArray(value) ? value : [value];
+    const files = [];
+    for (const item of given) {
+        const file = readInputFile(item, folder);
+        if (file === undefined) {
+            const shown = list ? `a list holding ${formatValue(item)}` : formatValue(value);
+            return `${method}() takes a path, a file such as { name: 'notes.txt', content: 'hello' }, or a list of them, received ${shown}.`;
+        }
+        if (typeof file === 'string')
+            return `${method}() ${file}`;
+        files.push(file);
+    }
+    const problem = inputFilesProblem(files, method);
+    return problem === undefined ? { files, list } : problem.message;
+}
+// One file, or undefined for something that is not one, or what is wrong with a file by content.
+function readInputFile(item, folder) {
+    if (typeof item === 'string')
+        return { path: item, folder };
+    if (!isPlainObject(item))
+        return undefined;
+    const given = Object.entries(item).filter(([, entry]) => entry !== undefined);
+    const unknown = given.find(([key]) => key !== 'name' && key !== 'mimeType' && key !== 'content');
+    if (unknown !== undefined)
+        return `has no file option ${JSON.stringify(unknown[0])}. A file by content takes name, mimeType and content.`;
+    const { name, mimeType, content } = Object.fromEntries(given);
+    if (typeof name !== 'string')
+        return `takes a file's name as text, received ${formatValue(name)}.`;
+    if (mimeType !== undefined && typeof mimeType !== 'string')
+        return `takes mimeType as text, such as 'text/plain', received ${formatValue(mimeType)}.`;
+    const bytes = typeof content === 'string' ? Buffer.from(content, 'utf8') : content instanceof Uint8Array ? Buffer.from(content.buffer, content.byteOffset, content.byteLength) : undefined;
+    if (bytes === undefined)
+        return `takes a file's content as text or bytes, received ${formatValue(content)}.`;
+    return { name, ...(mimeType === undefined ? {} : { mimeType }), base64: bytes.toString('base64') };
+}

package/dist/api/inbox.d.ts

@@ -0,0 +1,97 @@
+import type { InboxName } from '../config/register.ts';
+import type { InboxCodeRef, InboxLinkRef, ReceivedMessageRecord } from '../protocol/inbox.ts';
+import { Secret } from './secret.ts';
+/**
+ * How `latest()` reads: `subject` picks the newest message whose subject holds this text, in any case, or matches this
+ * `RegExp`, as the test reads the subject, with its codes and links replaced by placeholders. `timeout` is how long it
+ * looks, in milliseconds, the assertion budget by default, never longer than the test has left.
+ */
+export type InboxReadOptions = {
+    readonly subject?: string | RegExp | undefined;
+    readonly timeout?: number | undefined;
+};
+/** Which link `link()` takes: its number among the message's links, from 1, or the first whose path is `path` or lies under it. */
+export type LinkChoice = number | {
+    readonly path: string;
+};
+/**
+ * A link in a received message: the text it was shown under, its origin, and its path with each token in it replaced
+ * by its placeholder. `token` says whether it carries a token. Its query and fragment are never in the test's process.
+ */
+export type ReceivedLink = {
+    readonly text: string;
+    readonly origin: string;
+    readonly path: string;
+    readonly token: boolean;
+};
+/**
+ * A one-time code from a message, named but never held: the process that runs Retest types it, bound to origins as a
+ * secret is. It is a secret, so it goes only to `fill()`, and however it is printed it reads `{{code}}`.
+ */
+export declare class InboxCode extends Secret {
+    #private;
+    constructor(reference: InboxCodeRef);
+}
+/**
+ * A link from a message, named but never held: the process that runs Retest opens it, when its origin is one the test
+ * may open. It goes only to `goto()`, and however it is printed it reads `{{link}}`, or `{{link:2}}` when it was chosen
+ * by number or path.
+ */
+export declare class InboxLink {
+    #private;
+    constructor(reference: InboxLinkRef);
+    toString(): string;
+    toJSON(): string;
+}
+/**
+ * A message an inbox gave the test. `subject`, `from` and `text` have each code written `{{code}}` and each link that
+ * carries a token written `{{link:1}}`, `{{link:2}}` and so on, by its number. `code` is its first code, for `fill()`,
+ * and `link()` one of its links, for `goto()`; the test's process never holds either value.
+ */
+export declare class ReceivedMessage {
+    #private;
+    readonly subject: string;
+    readonly from: string;
+    readonly text: string;
+    /** When the mailbox received it. */
+    readonly receivedAt: Date;
+    readonly links: readonly ReceivedLink[];
+    /** The message's first code. A fill of it fails when the message holds none. */
+    readonly code: InboxCode;
+    constructor(record: ReceivedMessageRecord);
+    /**
+     * One of the message's links, for `goto()`. With no argument, the first link that carries a token, or else the first
+     * link. A number takes that link, from 1; `{ path }` the first link whose path is `path` or lies under it.
+     *
+     * @example await page.goto(message.link({ path: '/verify' }))
+     */
+    link(choice?: LinkChoice): InboxLink;
+}
+/** A test mailbox from the config, named for the reads a test makes of it. */
+export declare class Inbox {
+    #private;
+    constructor(name: string);
+    /** The inbox's name in the config. */
+    get name(): string;
+    /**
+     * Waits for the newest message the mailbox received since the test started, or since the last message this test was
+     * given from it, and gives it to the test. It looks again, as a matcher does, until one arrives or its time runs out.
+     *
+     * @example const message = await inbox('owner').latest({ subject: 'Your sign-in code' })
+     */
+    latest(options?: InboxReadOptions): Promise<ReceivedMessage>;
+}
+/**
+ * Names an inbox from the config, whose messages a test reads with `latest()`. The test's process never holds a code or
+ * a link that carries a token.
+ *
+ * @example
+ * const message = await inbox('owner').latest({ subject: 'Your sign-in code' })
+ * await page.getByLabel('Code').fill(message.code)
+ */
+export declare function inbox(name: InboxName): Inbox;
+/** The code a value names, when it is a code from an inbox. */
+export declare function inboxCodeReference(value: unknown): InboxCodeRef | undefined;
+/** The link a value names, when it is a link from an inbox. */
+export declare function inboxLinkReference(value: unknown): InboxLinkRef | undefined;
+//# sourceMappingURL=inbox.d.ts.map

package/dist/api/inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbox.d.ts","sourceRoot":"","sources":["../../src/api/inbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAgB,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAS3G,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEpC;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAExH,mIAAmI;AACnI,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3D;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAK7H;;;GAGG;AACH,qBAAa,SAAU,SAAQ,MAAM;;gBAOvB,SAAS,EAAE,YAAY;CAIpC;AAED;;;;GAIG;AACH,qBAAa,SAAS;;gBAaR,SAAS,EAAE,YAAY;IAInC,QAAQ,IAAI,MAAM;IAIlB,MAAM,IAAI,MAAM;CAGjB;AAED;;;;GAIG;AACH,qBAAa,eAAe;;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAA;IACvC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;gBAGZ,MAAM,EAAE,qBAAqB;IAUzC;;;;;OAKG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS;CA+BrC;AAED,8EAA8E;AAC9E,qBAAa,KAAK;;gBAGJ,IAAI,EAAE,MAAM;IAIxB,sCAAsC;IACtC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;CAS7D;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,SAAS,GAAG,KAAK,CAK5C;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAE3E;AAED,+DAA+D;AAC/D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,GAAG,SAAS,CAE3E"}

package/dist/api/inbox.js

@@ -0,0 +1,191 @@
+import { inspect } from 'node:util';
+import { describeInboxReference } from "../protocol/inbox.js";
+import { patternProblem, textPatternOf } from "../protocol/locator.js";
+import { isPlainObject } from "../protocol/schema.js";
+import { maxTimeout } from "../protocol/timeouts.js";
+import { requireScope } from "./context.js";
+import { formatValue } from "./format-value.js";
+import { misuse } from "./misuse.js";
+import { Secret } from "./secret.js";
+let codeReference;
+let linkReference;
+/**
+ * A one-time code from a message, named but never held: the process that runs Retest types it, bound to origins as a
+ * secret is. It is a secret, so it goes only to `fill()`, and however it is printed it reads `{{code}}`.
+ */
+export class InboxCode extends Secret {
+    #reference;
+    static {
+        codeReference = (code) => code.#reference;
+    }
+    constructor(reference) {
+        super('code');
+        this.#reference = reference;
+    }
+}
+/**
+ * A link from a message, named but never held: the process that runs Retest opens it, when its origin is one the test
+ * may open. It goes only to `goto()`, and however it is printed it reads `{{link}}`, or `{{link:2}}` when it was chosen
+ * by number or path.
+ */
+export class InboxLink {
+    #reference;
+    static {
+        linkReference = (link) => link.#reference;
+        // Node's inspect hook sits on the prototype, off the declared type, so the public type needs no Node types.
+        Object.defineProperty(InboxLink.prototype, inspect.custom, {
+            value() {
+                return this.toString();
+            },
+        });
+    }
+    constructor(reference) {
+        this.#reference = reference;
+    }
+    toString() {
+        return describeInboxReference(this.#reference);
+    }
+    toJSON() {
+        return this.toString();
+    }
+}
+/**
+ * A message an inbox gave the test. `subject`, `from` and `text` have each code written `{{code}}` and each link that
+ * carries a token written `{{link:1}}`, `{{link:2}}` and so on, by its number. `code` is its first code, for `fill()`,
+ * and `link()` one of its links, for `goto()`; the test's process never holds either value.
+ */
+export class ReceivedMessage {
+    subject;
+    from;
+    text;
+    /** When the mailbox received it. */
+    receivedAt;
+    links;
+    /** The message's first code. A fill of it fails when the message holds none. */
+    code;
+    #record;
+    constructor(record) {
+        this.#record = record;
+        this.subject = record.subject;
+        this.from = record.from;
+        this.text = record.text;
+        this.receivedAt = new Date(record.receivedAt);
+        this.links = Object.freeze(record.links.map((link) => Object.freeze({ ...link })));
+        this.code = new InboxCode({ inbox: record.inbox, message: record.id, code: 1 });
+    }
+    /**
+     * One of the message's links, for `goto()`. With no argument, the first link that carries a token, or else the first
+     * link. A number takes that link, from 1; `{ path }` the first link whose path is `path` or lies under it.
+     *
+     * @example await page.goto(message.link({ path: '/verify' }))
+     */
+    link(choice) {
+        const { inbox, id } = this.#record;
+        const chosen = this.#choose(choice);
+        if (typeof chosen === 'string')
+            throw misuse(chosen);
+        return new InboxLink({ inbox, message: id, link: chosen, ...(choice === undefined ? { default: true } : {}) });
+    }
+    // A link's number from 1, or why there is none to take.
+    #choose(choice) {
+        const { links } = this;
+        const subject = JSON.stringify(this.subject);
+        if (choice === undefined) {
+            if (links.length === 0)
+                return `link() found no link in the message ${subject}.`;
+            const carrying = links.findIndex((link) => link.token);
+            return (carrying === -1 ? 0 : carrying) + 1;
+        }
+        if (typeof choice === 'number') {
+            if (Number.isInteger(choice) && choice >= 1 && choice <= links.length)
+                return choice;
+            return `link(${formatValue(choice)}) takes a link's number from 1 to ${links.length}, the links of the message ${subject}.`;
+        }
+        if (isPlainObject(choice) && Object.keys(choice).length === 1 && typeof choice['path'] === 'string') {
+            const path = choice['path'];
+            const under = path.endsWith('/') ? path : `${path}/`;
+            const found = links.findIndex((link) => link.path === path || link.path.startsWith(under));
+            if (found !== -1)
+                return found + 1;
+            const paths = links.map((link) => link.path).filter((each) => each !== '');
+            const listed = paths.length === 0 ? 'Its links have no web address.' : `Its links go to ${paths.join(', ')}.`;
+            return `link({ path: ${JSON.stringify(path)} }) matches no link in the message ${subject}. ${listed}`;
+        }
+        return `link() takes a link's number from 1, such as link(2), or its path, such as link({ path: '/verify' }), received ${formatValue(choice)}.`;
+    }
+}
+/** A test mailbox from the config, named for the reads a test makes of it. */
+export class Inbox {
+    #name;
+    constructor(name) {
+        this.#name = name;
+    }
+    /** The inbox's name in the config. */
+    get name() {
+        return this.#name;
+    }
+    /**
+     * Waits for the newest message the mailbox received since the test started, or since the last message this test was
+     * given from it, and gives it to the test. It looks again, as a matcher does, until one arrives or its time runs out.
+     *
+     * @example const message = await inbox('owner').latest({ subject: 'Your sign-in code' })
+     */
+    latest(options) {
+        const call = `inbox(${JSON.stringify(this.#name)}).latest()`;
+        const { run } = requireScope(call);
+        const location = run.location();
+        const read = readOptions(options);
+        if (typeof read === 'string')
+            throw misuse(`${call} ${read}`, run);
+        const request = { inbox: this.#name, ...(read.subject === undefined ? {} : { subject: read.subject }) };
+        return run.readInbox({ label: call, request, location, ...(read.timeoutMs === undefined ? {} : { timeoutMs: read.timeoutMs }) }, (record) => new ReceivedMessage(record));
+    }
+}
+/**
+ * Names an inbox from the config, whose messages a test reads with `latest()`. The test's process never holds a code or
+ * a link that carries a token.
+ *
+ * @example
+ * const message = await inbox('owner').latest({ subject: 'Your sign-in code' })
+ * await page.getByLabel('Code').fill(message.code)
+ */
+export function inbox(name) {
+    // Read as JavaScript passed it: a registered config narrows the type, not what arrives.
+    const given = name;
+    if (typeof given !== 'string' || given === '')
+        throw misuse(`inbox() takes the name of an inbox from the config, received ${formatValue(given)}.`);
+    return new Inbox(given);
+}
+/** The code a value names, when it is a code from an inbox. */
+export function inboxCodeReference(value) {
+    return value instanceof InboxCode ? codeReference?.(value) : undefined;
+}
+/** The link a value names, when it is a link from an inbox. */
+export function inboxLinkReference(value) {
+    return value instanceof InboxLink ? linkReference?.(value) : undefined;
+}
+// Every option is checked, because JavaScript callers have no types. A key set to undefined counts as absent.
+function readOptions(options) {
+    if (options === undefined)
+        return {};
+    if (!isPlainObject(options))
+        return `takes options such as { subject: 'Your code', timeout: 10_000 }, received ${formatValue(options)}.`;
+    const given = Object.entries(options).filter(([, value]) => value !== undefined);
+    const unknown = given.find(([key]) => key !== 'subject' && key !== 'timeout');
+    if (unknown !== undefined)
+        return `has no option ${JSON.stringify(unknown[0])}. It takes subject and timeout.`;
+    const { subject, timeout } = Object.fromEntries(given);
+    if (timeout !== undefined && !(typeof timeout === 'number' && Number.isInteger(timeout) && timeout >= 1 && timeout <= maxTimeout)) {
+        return `takes timeout as a whole number of milliseconds from 1 to ${maxTimeout}, received ${formatValue(timeout)}.`;
+    }
+    const timed = timeout === undefined ? {} : { timeoutMs: timeout };
+    if (subject === undefined)
+        return timed;
+    if (typeof subject === 'string')
+        return subject === '' ? 'takes subject as text to find in the subject, received an empty string.' : { subject, ...timed };
+    if (!(subject instanceof RegExp))
+        return `takes subject as text or a RegExp, received ${formatValue(subject)}.`;
+    const pattern = textPatternOf(subject);
+    const problem = patternProblem(pattern);
+    return problem === undefined ? { subject: pattern, ...timed } : `received a subject RegExp Retest cannot read: ${problem}.`;
+}