@rehearsal-labs/retest 0.1.0 → 0.3.0

package/dist/api/route.js

@@ -0,0 +1,99 @@
+import { textPatternOf } from "../protocol/locator.js";
+import { abortReasons, describeRoutePattern, routeAnswerProblem, routePatternProblem } from "../protocol/routes.js";
+import { isPlainObject } from "../protocol/schema.js";
+import { listWords } from "../shared/list-words.js";
+import { formatValue } from "./format-value.js";
+import { misuse } from "./misuse.js";
+const fulfilKeys = new Set(['status', 'headers', 'contentType', 'body']);
+/**
+ * Adds a route to the app's page: from now on every request of the page whose address `pattern` matches is answered
+ * with `answer`, before any route added earlier. Resolves once the page holds it.
+ *
+ * @example await route(page, 'http://127.0.0.1:4173/api/tasks', { status: 200, contentType: 'application/json', body: '[]' })
+ */
+export function route({ run, app }, pattern, answer) {
+    const location = run.location();
+    const read = readPattern(pattern, 'route', run);
+    const record = readAnswer(answer, run);
+    return run.changeRoutes({ app, label: `page.route(${describeRoutePattern(read)})`, request: { kind: 'add', pattern: read, answer: record }, location });
+}
+/**
+ * Removes every route of the app's page added with `pattern`, written as it was. Resolves once the page holds the change.
+ *
+ * @example await unroute(page, 'http://127.0.0.1:4173/api/tasks')
+ */
+export function unroute({ run, app }, pattern) {
+    const location = run.location();
+    const read = readPattern(pattern, 'unroute', run);
+    return run.changeRoutes({ app, label: `page.unroute(${describeRoutePattern(read)})`, request: { kind: 'remove', pattern: read }, location });
+}
+function readPattern(pattern, method, run) {
+    const read = typeof pattern === 'string' ? pattern : pattern instanceof RegExp ? textPatternOf(pattern) : undefined;
+    if (read === undefined)
+        throw misuse(`page.${method}() takes a glob of the whole address, such as '**/api/tasks', or a RegExp, received ${formatValue(pattern)}.`, run);
+    const problem = routePatternProblem(read, method);
+    if (problem !== undefined)
+        throw misuse(problem, run);
+    return read;
+}
+// An answer is data, since no function crosses to the process that runs the browser: each part is read as the wire
+// carries it, and a body of bytes goes as base64.
+function readAnswer(answer, run) {
+    if (!isPlainObject(answer))
+        throw misuse(`page.route() takes an answer such as { status: 200, body: 'ok' } or { abort: 'connectionrefused' }, received ${formatValue(answer)}.`, run);
+    const given = Object.entries(answer).filter(([, value]) => value !== undefined);
+    const unknown = given.find(([key]) => key !== 'abort' && !fulfilKeys.has(key));
+    if (unknown !== undefined)
+        throw misuse(`page.route() has no answer option ${JSON.stringify(unknown[0])}. An answer takes status, headers, contentType and body, or abort.`, run);
+    const parts = Object.fromEntries(given);
+    if ('abort' in parts) {
+        if (given.length > 1)
+            throw misuse('page.route() takes an answer that gives a response or one that aborts the request, not both.', run);
+        const reason = abortReasons.find((each) => each === parts['abort']);
+        if (reason === undefined)
+            throw misuse(`page.route() takes abort as one of ${listWords(abortReasons.map((each) => `'${each}'`), 'or')}, received ${formatValue(parts['abort'])}.`, run);
+        return { abort: reason };
+    }
+    const record = { ...status(parts['status'], run), ...headers(parts['headers'], run), ...contentType(parts['contentType'], run), ...body(parts['body'], run) };
+    const problem = routeAnswerProblem(record);
+    if (problem !== undefined)
+        throw misuse(problem, run);
+    return record;
+}
+function status(value, run) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'number')
+        throw misuse(`page.route() takes status as a number, such as 404, received ${formatValue(value)}.`, run);
+    return { status: value };
+}
+function headers(value, run) {
+    if (value === undefined)
+        return {};
+    const refused = () => misuse(`page.route() takes headers as names with text values, such as { 'x-total': '3' }, received ${formatValue(value)}.`, run);
+    if (!isPlainObject(value))
+        throw refused();
+    const read = {};
+    for (const [name, header] of Object.entries(value)) {
+        if (typeof header !== 'string')
+            throw refused();
+        read[name] = header;
+    }
+    return { headers: read };
+}
+function contentType(value, run) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'string')
+        throw misuse(`page.route() takes contentType as text, such as 'application/json', received ${formatValue(value)}.`, run);
+    return { contentType: value };
+}
+function body(value, run) {
+    if (value === undefined)
+        return {};
+    if (typeof value === 'string')
+        return { body: value };
+    if (value instanceof Uint8Array)
+        return { base64: Buffer.from(value.buffer, value.byteOffset, value.byteLength).toString('base64') };
+    throw misuse(`page.route() takes a body as text or bytes, received ${formatValue(value)}.`, run);
+}

package/dist/api/source-location.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-location.d.ts","sourceRoot":"","sources":["../../src/api/source-location.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAY7D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAM1E;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAOvF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG3F"}
+{"version":3,"file":"source-location.d.ts","sourceRoot":"","sources":["../../src/api/source-location.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAc7D;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAM1E;AAED,oGAAoG;AACpG,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAOvF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAG3F"}

package/dist/api/source-location.js

@@ -5,7 +5,9 @@ import { formatLine } from "../protocol/location.js";
 import { relativePosixPath } from "../shared/posix-path.js";
 // The folder holding this copy of Retest: `src` when run from source, `dist` when built.
 const ownDirectory = fileURLToPath(new URL('../', import.meta.url));
-const stackFrame = /(?:\(|at )((?:file:\/\/)?\/[^()]*?):(\d+):(\d+)\)?$/;
+// A frame names its script by a file URL or an absolute path: a POSIX one, or on Windows a drive or UNC path, as V8
+// writes a frame a source map placed.
+const stackFrame = /(?:\(|at )((?:file:\/\/)?\/[^()]*?|[A-Za-z]:[\\/][^()]*?|\\\\[^()]*?):(\d+):(\d+)\)?$/;
 const maxFrames = 64;
 /**
  * Where the code that called into Retest sits: the first stack frame outside Retest's own files.

package/dist/api/test-run.d.ts

@@ -2,9 +2,16 @@ import type { ObserveAfter, CommandResult, PageCommand } from '../protocol/comma
 import type { EvaluationAnswer, EvaluationCall } from '../protocol/evaluation.ts';
 import type { ChildEvent } from '../protocol/events.ts';
 import type { Failure, SourceLocation } from '../protocol/failures.ts';
+import type { DialogAnswer, DialogRecord } from '../protocol/dialogs.ts';
+import type { FilesAnswer, FilesRequest } from '../protocol/files.ts';
+import type { RouteReply, RouteRequest } from '../protocol/routes.ts';
+import type { InboxAnswer, InboxRequest, ReceivedMessageRecord } from '../protocol/inbox.ts';
+import type { LayoutRequest } from '../protocol/layout-checks.ts';
 import type { LocatorRecipe } from '../protocol/locator.ts';
 import type { ChildMessage } from '../protocol/messages.ts';
+import type { ScreenshotRequest } from '../protocol/screenshot.ts';
 import type { Timeouts } from '../protocol/timeouts.ts';
+import type { PopupAnswer, PopupRecord } from '../protocol/popups.ts';
 import type { RunTime } from './run-time.ts';
 import type { RunnableTest } from './test-body.ts';
 import { RetestError } from './failure.ts';
@@ -27,6 +34,58 @@ export type TestRunOptions = {
     /** The clock the test's budgets and durations count on, and the waits assertions poll with. The host's by default. */
     time?: RunTime;
 };
+/**
+ * A read of an inbox as the test asked for it: the call as the test wrote it, what it asks for, where the test sent it
+ * from, and the time it gave itself with `{ timeout }`, when it gave one.
+ */
+export type InboxReading = {
+    readonly label: string;
+    readonly request: InboxRequest;
+    readonly location: SourceLocation | undefined;
+    readonly timeoutMs?: number;
+};
+/**
+ * A wait the parent makes about files, as the test asked for it: the call as the test wrote it, what it waits for, where
+ * the test sent it from, and its time in milliseconds, before the test's own time left cuts it.
+ */
+export type FilesWaiting = {
+    readonly label: string;
+    readonly request: FilesRequest;
+    readonly location: SourceLocation | undefined;
+    readonly timeoutMs: number;
+};
+/**
+ * A wait for what an action opens on an app's page, as the test asked for it: the app, the call as the test wrote it,
+ * where the test sent it from, the time it gave itself with `{ timeout }`, when it gave one, and the action, which the
+ * wait runs once the page is armed.
+ */
+export type OpeningWait = {
+    readonly app: string;
+    readonly label: string;
+    readonly location: SourceLocation | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly action: () => Promise<unknown>;
+};
+/**
+ * An answer to a dialog the test was given: the app whose page shows it, its id, whether to accept it and the text a
+ * prompt takes, the call as the test wrote it and where, and the action that opened it, which the answer waits for.
+ */
+export type DialogAnswering = {
+    readonly app: string;
+    readonly dialog: string;
+    readonly accept: boolean;
+    readonly promptText?: string | undefined;
+    readonly label: string;
+    readonly location: SourceLocation | undefined;
+    readonly acted: Promise<void>;
+};
+/** A change to an app's routes, as the test asked for it: the app, the call as the test wrote it, and where it was sent from. */
+export type RouteChange = {
+    readonly app: string;
+    readonly label: string;
+    readonly request: RouteRequest;
+    readonly location: SourceLocation | undefined;
+};
 /** How a test ended, as the child reports it. */
 export type Verdict = {
     status: 'passed' | 'failed';
@@ -35,7 +94,7 @@ export type Verdict = {
     durationMs: number;
 };
 type ActionCommand = Exclude<PageCommand, {
-    kind: 'observe' | 'observePage';
+    kind: 'observe' | 'observePage' | 'observeLayout' | 'observeScreenshot';
 }>;
 /**
  * One test running in the child. It runs the test's hooks and function, sends each app's commands one at a
@@ -78,6 +137,62 @@ export declare class TestRun {
      * earlier test never reaches a later one.
      */
     requestEvaluation(call: EvaluationCall, location: SourceLocation | undefined): Promise<EvaluationAnswer>;
+    /**
+     * Asks the parent to read an inbox. The parent reads the mailbox, looks again until a message arrives or the read's
+     * time runs out, and answers with the message, its codes and links hidden; `wrap` turns that answer into what the
+     * test receives. The read touches no page, so it holds no app, and it starts at once. Its time is its own `timeoutMs`,
+     * or the assertion budget, cut to what the test has left. It changes what the next read gives, so it may not run
+     * inside the function `expect.poll` calls.
+     */
+    readInbox<T>({ label, request, location, timeoutMs }: InboxReading, wrap: (message: ReceivedMessageRecord) => T): Operation<T>;
+    resolveInbox(id: number, answer: InboxAnswer): void;
+    /**
+     * Asks the parent to arm an app's page for the next JavaScript dialog, runs the action once the page is armed, and
+     * resolves with what `wrap` makes of the dialog as soon as it opens. The action is still waiting then, since a page
+     * holds the input that opened a dialog until the dialog is answered; `wrap` is given the action's own promise, which
+     * settles once the action does. An action that fails before any dialog opened fails the wait with its own failure,
+     * and the parent stops waiting. A wait that sees no dialog in its time fails, unless its action failed meanwhile,
+     * whose failure it gives instead. The wait acts on a page, so it may not run inside the function `expect.poll` calls.
+     */
+    waitForDialog<T>(wait: OpeningWait, wrap: (dialog: DialogRecord, acted: Promise<void>) => T): Operation<T>;
+    /**
+     * As `waitForDialog`, for the next page the action opens: the parent hands it over as an app of its own, and the wait
+     * resolves with what `wrap` makes of it once the action is over too, so the next command to the page that opened it
+     * never meets the action still running. An action that fails fails the wait with its own failure.
+     */
+    waitForPopup<T>(wait: OpeningWait, wrap: (popup: PopupRecord) => T): Operation<T>;
+    /**
+     * Asks the parent to answer a dialog the test was given, then waits for the action that opened it, so the answer's
+     * step ends once its action has. An answer the parent could not give fails, and an action that failed fails it too,
+     * with its own failure. It acts on a page, so it may not run inside the function `expect.poll` calls.
+     */
+    answerDialog({ app, dialog, accept, promptText, label, location, acted }: DialogAnswering): Operation<void>;
+    resolveDialog(id: number, answer: DialogAnswer): void;
+    resolvePopup(id: number, answer: PopupAnswer): void;
+    /**
+     * Asks the parent to wait for what `request` names, runs `action` meanwhile when one is given, and resolves with what
+     * `wrap` makes of the parent's answer once the action is over and the parent has answered. The wait holds no app, so
+     * the action's own commands go as they would without it; the request goes first, so the parent is waiting before
+     * the action's first command arrives. An action that fails fails the wait with its own failure, and the parent lets go
+     * of what it armed. A wait with an action acts on a page, so it may not run inside the function `expect.poll` calls.
+     */
+    awaitFiles<T>({ label, request, location, timeoutMs }: FilesWaiting, wrap: (answer: Extract<FilesAnswer, {
+        ok: true;
+    }>) => T | Promise<T>, action?: () => unknown): Operation<T>;
+    resolveFiles(id: number, answer: FilesAnswer): void;
+    /**
+     * Asks the parent to change an app's routes, and resolves once the page holds the change, so the test's next command
+     * to the page meets it. It needs the app to itself, as an action does: a request already on its way when the routes
+     * change could meet either. Its time is the action budget, cut to what the test has left. It changes what the page's
+     * requests get, so it may not run inside the function `expect.poll` calls.
+     */
+    changeRoutes({ app, label, request, location }: RouteChange): Operation<void>;
+    resolveRoute(id: number, answer: RouteReply): void;
+    /**
+     * The folder a path a test wrote is read against, as an import's is: that of the file the call came from, or the
+     * test's own file when the call's place is unknown.
+     */
+    callerFolder(location: SourceLocation | undefined): string;
     resolveEvaluation(id: number, answer: EvaluationAnswer): void;
     emit(event: ChildEvent): void;
     countAssertion(): void;
@@ -104,6 +219,17 @@ export declare class TestRun {
      * change. The look is marked as a check's, as `observe` marks its own.
      */
     observePage(app: string, timeoutMs: number, location: SourceLocation | undefined, after?: ObserveAfter): Promise<CommandResult>;
+    /**
+     * Measures an app's page once for a layout assertion: the elements `request` names, and their words when it asks. With
+     * `after`, the page first waits for its next change. The look is marked as a check's, as `observe` marks its own.
+     */
+    observeLayout(app: string, request: LayoutRequest, timeoutMs: number, location: SourceLocation | undefined, after?: ObserveAfter): Promise<CommandResult>;
+    /**
+     * Takes a picture of an app's page, or of one element, for a screenshot assertion, and learns its size and how it
+     * stands against its baseline; the pixels stay with the parent. `previous` names the look before it in the same check,
+     * whose picture this one must match to have settled. The look is marked as a check's, as `observe` marks its own.
+     */
+    observeScreenshot(app: string, request: ScreenshotRequest, previous: string | undefined, timeoutMs: number, location: SourceLocation | undefined): Promise<CommandResult>;
     /**
      * Reads an app's page once outside any check, its address and title, as `page.url()` and `page.title()` do inside
      * `read`. No assertion follows such a look, so it is not marked as a check's.

package/dist/api/test-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-run.d.ts","sourceRoot":"","sources":["../../src/api/test-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AACjF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAEvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,EAAQ,YAAY,EAAkB,MAAM,gBAAgB,CAAA;AAQxE,OAAO,EAAgC,WAAW,EAAE,MAAM,cAAc,CAAA;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAK1C,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,cAAc,CAAA;IACxB,QAAQ,EAAE,QAAQ,CAAA;IAClB,8GAA8G;IAC9G,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IACvB,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;IACrC,+GAA+G;IAC/G,aAAa,EAAE,MAAM,MAAM,CAAA;IAC3B,sHAAsH;IACtH,IAAI,CAAC,EAAE,OAAO,CAAA;CACf,CAAA;AAED,iDAAiD;AACjD,MAAM,MAAM,OAAO,GAAG;IAAE,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpH,KAAK,aAAa,GAAG,OAAO,CAAC,WAAW,EAAE;IAAE,IAAI,EAAE,SAAS,GAAG,aAAa,CAAA;CAAE,CAAC,CAAA;AAa9E;;;;GAIG;AACH,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBAeV,OAAO,EAAE,cAAc;IAWnC,gGAAgG;IAChG,IAAI,IAAI,IAAI,SAAS,MAAM,EAAE,CAE5B;IAED,wDAAwD;IACxD,QAAQ,IAAI,cAAc,GAAG,SAAS;IAItC,wFAAwF;IACxF,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW;IAKnC,sGAAsG;IACtG,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI9B;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI;IAMpD;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;IAcnD,sFAAsF;IACtF,KAAK,IAAI,IAAI;IAMb,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAOvD;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;IASxG,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAO7D,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAI7B,cAAc,IAAI,IAAI;IAItB,yGAAyG;IACzG,eAAe,CAAC,KAAK,GAAE,MAAgC,GAAG,MAAM;IAIhE;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC;IAyBrH;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC;IAM7I;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAMnJ;;;OAGG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,KAAK,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC;IAM/H;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC;IAMtG;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAsB/G,qEAAqE;IACrE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,GAAG,SAAS,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAwB5H,kGAAkG;IAClG,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,SAAS,GAAG,MAAM;CAsK3D"}
+{"version":3,"file":"test-run.d.ts","sourceRoot":"","sources":["../../src/api/test-run.ts"],"names":[],"mappings":"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"}

package/dist/api/test-run.js

@@ -1,3 +1,4 @@
+import { dirname, join } from 'node:path';
 import { describeCommand } from "../protocol/commands.js";
 import { Deadline, elapsedMs, smallestBudget } from "../protocol/deadline.js";
 import { failure, withAlso, withLocation } from "../protocol/failures.js";
@@ -30,6 +31,13 @@ export class TestRun {
     #failures = [];
     #answers = new Map();
     #evaluations = new Map();
+    #inboxReads = new Map();
+    // Waits for dialogs and popups and answers to dialogs, by id; a wait is answered more than once, armed then opened.
+    #pageWaits = new Map();
+    // The dialogs the test was given and has not answered yet, by id, with where it asked for each.
+    #dialogsOpen = new Map();
+    #filesRequests = new Map();
+    #routeChanges = new Map();
     #lanes = new CommandLanes();
     #aborted = Promise.withResolvers();
     // Work created since the last function the test ran returned; each function answers for its own.
@@ -122,6 +130,246 @@ export class TestRun {
         this.#options.send({ type: 'evaluate', testId: this.testId, attemptId: this.attemptId, id, call, ...(location === undefined ? {} : { location }), ...(stepId === undefined ? {} : { stepId }) });
         return promise;
     }
+    /**
+     * Asks the parent to read an inbox. The parent reads the mailbox, looks again until a message arrives or the read's
+     * time runs out, and answers with the message, its codes and links hidden; `wrap` turns that answer into what the
+     * test receives. The read touches no page, so it holds no app, and it starts at once. Its time is its own `timeoutMs`,
+     * or the assertion budget, cut to what the test has left. It changes what the next read gives, so it may not run
+     * inside the function `expect.poll` calls.
+     */
+    readInbox({ label, request, location, timeoutMs }, wrap) {
+        const work = { label, location };
+        const operation = this.#track('read', work);
+        const refusal = this.#refusal() ?? this.#whileReading(work);
+        if (refusal !== undefined) {
+            operation.reject(refusal);
+            return operation;
+        }
+        const id = this.#options.nextCommandId();
+        const stepId = currentScope()?.stepId;
+        this.#inboxReads.set(id, (answer) => {
+            if (answer.ok)
+                operation.resolve(wrap(answer.message));
+            else
+                operation.reject(this.fail(withLocation(answer.failure, location)));
+        });
+        const budget = this.assertionBudget(timeoutMs ?? this.timeouts.assertion);
+        this.#options.send({ type: 'inbox', testId: this.testId, attemptId: this.attemptId, id, request, timeoutMs: budget, ...(location === undefined ? {} : { location }), ...(stepId === undefined ? {} : { stepId }) });
+        return operation;
+    }
+    resolveInbox(id, answer) {
+        const resolve = this.#inboxReads.get(id);
+        if (resolve === undefined)
+            return;
+        this.#inboxReads.delete(id);
+        resolve(answer);
+    }
+    /**
+     * Asks the parent to arm an app's page for the next JavaScript dialog, runs the action once the page is armed, and
+     * resolves with what `wrap` makes of the dialog as soon as it opens. The action is still waiting then, since a page
+     * holds the input that opened a dialog until the dialog is answered; `wrap` is given the action's own promise, which
+     * settles once the action does. An action that fails before any dialog opened fails the wait with its own failure,
+     * and the parent stops waiting. A wait that sees no dialog in its time fails, unless its action failed meanwhile,
+     * whose failure it gives instead. The wait acts on a page, so it may not run inside the function `expect.poll` calls.
+     */
+    waitForDialog(wait, wrap) {
+        return this.#waitForOpening('dialog', wait, (answer, acted) => {
+            if (!('dialog' in answer))
+                throw new Error('Retest answered a wait for a dialog with a page');
+            this.#dialogsOpen.set(answer.dialog.id, { type: answer.dialog.type, location: wait.location });
+            return wrap(answer.dialog, acted);
+        });
+    }
+    /**
+     * As `waitForDialog`, for the next page the action opens: the parent hands it over as an app of its own, and the wait
+     * resolves with what `wrap` makes of it once the action is over too, so the next command to the page that opened it
+     * never meets the action still running. An action that fails fails the wait with its own failure.
+     */
+    waitForPopup(wait, wrap) {
+        return this.#waitForOpening('popup', wait, async (answer, acted) => {
+            if (!('popup' in answer))
+                throw new Error('Retest answered a wait for a page with a dialog');
+            await acted;
+            return wrap(answer.popup);
+        });
+    }
+    /**
+     * Asks the parent to answer a dialog the test was given, then waits for the action that opened it, so the answer's
+     * step ends once its action has. An answer the parent could not give fails, and an action that failed fails it too,
+     * with its own failure. It acts on a page, so it may not run inside the function `expect.poll` calls.
+     */
+    answerDialog({ app, dialog, accept, promptText, label, location, acted }) {
+        const work = { label, location };
+        const operation = this.#track('read', work);
+        const refusal = this.#refusal() ?? this.#whileReading(work);
+        if (refusal !== undefined) {
+            operation.reject(refusal);
+            return operation;
+        }
+        this.#dialogsOpen.delete(dialog);
+        const id = this.#options.nextCommandId();
+        const stepId = currentScope()?.stepId;
+        this.#pageWaits.set(id, (answer) => {
+            this.#pageWaits.delete(id);
+            if (answer.kind === 'answered')
+                acted.then(() => operation.resolve(), (error) => operation.reject(error));
+            else if (answer.kind === 'failed')
+                operation.reject(this.fail(withLocation(answer.failure, location)));
+        });
+        const request = { kind: 'answer', dialog, accept, ...(promptText === undefined ? {} : { promptText }) };
+        const timeoutMs = this.assertionBudget(this.timeouts.action);
+        this.#options.send({ type: 'dialog', testId: this.testId, attemptId: this.attemptId, id, app, request, timeoutMs, ...(location === undefined ? {} : { location }), ...(stepId === undefined ? {} : { stepId }) });
+        return operation;
+    }
+    resolveDialog(id, answer) {
+        this.#pageWaits.get(id)?.(answer);
+    }
+    resolvePopup(id, answer) {
+        this.#pageWaits.get(id)?.(answer);
+    }
+    // The wait is armed before the action runs, so the parent hands over what the action's first command opens. The
+    // answer to the request comes on another turn, so the action runs in the scope the test called from, as its step.
+    #waitForOpening(kind, { app, label, location, timeoutMs, action }, take) {
+        const work = { label, location };
+        const operation = this.#track('read', work);
+        const refusal = this.#refusal() ?? this.#whileReading(work);
+        if (refusal !== undefined) {
+            operation.reject(refusal);
+            return operation;
+        }
+        const scope = currentScope() ?? { run: this };
+        const id = this.#options.nextCommandId();
+        const sending = { app, location, stepId: scope.stepId };
+        let acted;
+        let opened = false;
+        const fail = (problem) => operation.reject(this.fail(withLocation(problem, location)));
+        this.#pageWaits.set(id, (answer) => {
+            if (answer.kind === 'armed') {
+                const running = callInScope(scope, action).then(() => undefined);
+                acted = running;
+                running.then(undefined, (error) => {
+                    if (opened)
+                        return;
+                    this.#pageWaits.delete(id);
+                    this.#sendWait(kind, this.#options.nextCommandId(), { kind: 'stop', wait: id }, 1, sending);
+                    operation.reject(error);
+                });
+                return;
+            }
+            this.#pageWaits.delete(id);
+            if (answer.kind === 'opened') {
+                opened = true;
+                // The action may still be running: `take` is given its promise, so its own end is never lost.
+                const settled = acted ?? Promise.resolve();
+                Promise.resolve()
+                    .then(() => take(answer, settled))
+                    .then((value) => operation.resolve(value), (error) => operation.reject(error));
+                return;
+            }
+            if (answer.kind !== 'failed')
+                return;
+            // The action's own failure says more than a wait that saw nothing while the action ran.
+            if (acted === undefined)
+                fail(answer.failure);
+            else
+                acted.then(() => fail(answer.failure), (error) => operation.reject(error));
+        });
+        this.#sendWait(kind, id, { kind: 'wait' }, this.assertionBudget(timeoutMs ?? this.timeouts.action), sending);
+        return operation;
+    }
+    #sendWait(kind, id, request, timeoutMs, { app, location, stepId }) {
+        const scope = { testId: this.testId, attemptId: this.attemptId, id, app, timeoutMs, ...(location === undefined ? {} : { location }), ...(stepId === undefined ? {} : { stepId }) };
+        this.#options.send(kind === 'dialog' ? { type: 'dialog', ...scope, request } : { type: 'popup', ...scope, request });
+    }
+    /**
+     * Asks the parent to wait for what `request` names, runs `action` meanwhile when one is given, and resolves with what
+     * `wrap` makes of the parent's answer once the action is over and the parent has answered. The wait holds no app, so
+     * the action's own commands go as they would without it; the request goes first, so the parent is waiting before
+     * the action's first command arrives. An action that fails fails the wait with its own failure, and the parent lets go
+     * of what it armed. A wait with an action acts on a page, so it may not run inside the function `expect.poll` calls.
+     */
+    awaitFiles({ label, request, location, timeoutMs }, wrap, action) {
+        const work = { label, location };
+        const operation = this.#track('read', work);
+        const refusal = this.#refusal() ?? (action === undefined ? undefined : this.#whileReading(work));
+        if (refusal !== undefined) {
+            operation.reject(refusal);
+            return operation;
+        }
+        const id = this.#sendFiles(request, smallestBudget(timeoutMs, this.#deadline.commandTimeoutMs), location);
+        const answered = new Promise((resolve) => this.#filesRequests.set(id, resolve));
+        started(action).then(async () => {
+            const answer = await answered;
+            if (!answer.ok)
+                return operation.reject(this.fail(withLocation(answer.failure, location)));
+            try {
+                operation.resolve(await wrap(answer));
+            }
+            catch (error) {
+                operation.reject(error);
+            }
+        }, (error) => {
+            this.#filesRequests.delete(id);
+            this.#sendFiles({ kind: 'release', request: id }, 1, location);
+            operation.reject(error);
+        });
+        return operation;
+    }
+    resolveFiles(id, answer) {
+        const resolve = this.#filesRequests.get(id);
+        if (resolve === undefined)
+            return;
+        this.#filesRequests.delete(id);
+        resolve(answer);
+    }
+    /**
+     * Asks the parent to change an app's routes, and resolves once the page holds the change, so the test's next command
+     * to the page meets it. It needs the app to itself, as an action does: a request already on its way when the routes
+     * change could meet either. Its time is the action budget, cut to what the test has left. It changes what the page's
+     * requests get, so it may not run inside the function `expect.poll` calls.
+     */
+    changeRoutes({ app, label, request, location }) {
+        const work = { label, location };
+        const operation = this.#track('read', work);
+        const refusal = this.#refusal() ?? this.#whileReading(work) ?? this.#clash(app, work, 'action');
+        if (refusal !== undefined) {
+            operation.reject(refusal);
+            return operation;
+        }
+        this.#lanes.startAction(app, work);
+        const id = this.#options.nextCommandId();
+        const stepId = currentScope()?.stepId;
+        this.#routeChanges.set(id, (answer) => {
+            this.#lanes.endAction(app, work);
+            if (answer.ok)
+                operation.resolve();
+            else
+                operation.reject(this.fail(withLocation(answer.failure, location)));
+        });
+        const timeoutMs = this.assertionBudget(this.timeouts.action);
+        this.#options.send({ type: 'route', testId: this.testId, attemptId: this.attemptId, id, app, request, timeoutMs, ...(location === undefined ? {} : { location }), ...(stepId === undefined ? {} : { stepId }) });
+        return operation;
+    }
+    resolveRoute(id, answer) {
+        const resolve = this.#routeChanges.get(id);
+        if (resolve === undefined)
+            return;
+        this.#routeChanges.delete(id);
+        resolve(answer);
+    }
+    /**
+     * The folder a path a test wrote is read against, as an import's is: that of the file the call came from, or the
+     * test's own file when the call's place is unknown.
+     */
+    callerFolder(location) {
+        return dirname(join(this.#options.rootDir, location?.file ?? this.#options.file));
+    }
+    #sendFiles(request, timeoutMs, location) {
+        const id = this.#options.nextCommandId();
+        const stepId = currentScope()?.stepId;
+        this.#options.send({ type: 'files', testId: this.testId, attemptId: this.attemptId, id, request, timeoutMs, ...(location === undefined ? {} : { location }), ...(stepId === undefined ? {} : { stepId }) });
+        return id;
+    }
     resolveEvaluation(id, answer) {
         const resolve = this.#evaluations.get(id);
         if (resolve === undefined)
@@ -201,6 +449,27 @@ export class TestRun {
             return Promise.resolve({ ok: false, failure: refusal.failure });
         return this.#send(app, { kind: 'observePage', ...(after === undefined ? {} : { after }), check: true }, { timeoutMs, location });
     }
+    /**
+     * Measures an app's page once for a layout assertion: the elements `request` names, and their words when it asks. With
+     * `after`, the page first waits for its next change. The look is marked as a check's, as `observe` marks its own.
+     */
+    observeLayout(app, request, timeoutMs, location, after) {
+        const refusal = this.#refusal();
+        if (refusal !== undefined)
+            return Promise.resolve({ ok: false, failure: refusal.failure });
+        return this.#send(app, { kind: 'observeLayout', ...request, ...(after === undefined ? {} : { after }), check: true }, { timeoutMs, location });
+    }
+    /**
+     * Takes a picture of an app's page, or of one element, for a screenshot assertion, and learns its size and how it
+     * stands against its baseline; the pixels stay with the parent. `previous` names the look before it in the same check,
+     * whose picture this one must match to have settled. The look is marked as a check's, as `observe` marks its own.
+     */
+    observeScreenshot(app, request, previous, timeoutMs, location) {
+        const refusal = this.#refusal();
+        if (refusal !== undefined)
+            return Promise.resolve({ ok: false, failure: refusal.failure });
+        return this.#send(app, { kind: 'observeScreenshot', ...request, ...(previous === undefined ? {} : { previous }), check: true }, { timeoutMs, location });
+    }
     /**
      * Reads an app's page once outside any check, its address and title, as `page.url()` and `page.title()` do inside
      * `read`. No assertion follows such a look, so it is not marked as a check's.
@@ -291,6 +560,8 @@ export class TestRun {
         await yieldToEventLoop();
         if (ending.kind === 'threw')
             this.recordThrown(ending.error);
+        for (const problem of this.#dialogsLeftOpen(what))
+            this.record(problem);
         for (const problem of this.#unfinishedWork(what))
             this.record(problem);
         return ending;
@@ -400,6 +671,15 @@ export class TestRun {
     #isRecorded(error) {
         return error instanceof RetestError && this.#failures.includes(error.failure);
     }
+    // A dialog the test was given and never answered holds its page, and the action that opened it cannot finish.
+    #dialogsLeftOpen(what) {
+        const open = [...this.#dialogsOpen.values()];
+        this.#dialogsOpen.clear();
+        return open.map(({ type, location }) => {
+            const message = `The ${type} dialog page.dialog() gave on ${this.describeLine(location)} was still open when ${what} returned. Answer it with dialog.accept() or dialog.dismiss().`;
+            return failure('not_awaited', message, location);
+        });
+    }
     // Judges the work created since the last function returned, then forgets it.
     #unfinishedWork(what) {
         const tracked = this.#tracked;
@@ -431,10 +711,23 @@ function calledMethod(command) {
             return `keyboard.${command.operation}`;
         case 'nativeAlert':
             return `alert.${command.operation}`;
+        case 'setChooserFiles':
+            return 'setFiles';
         default:
             return command.kind;
     }
 }
+// A function the test passed, started at once; what it throws as it starts is its failure, as what it rejects with is.
+function started(action) {
+    if (action === undefined)
+        return Promise.resolve();
+    try {
+        return Promise.resolve(action());
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+}
 function lineOrNull(location) {
     return location === undefined ? null : formatLine(location);
 }