@rehearsal-labs/retest 0.1.0 → 0.2.0

package/dist/browser/electron-window-watch.js

@@ -0,0 +1,93 @@
+import { waitUntilDeadline } from "../assertions/wait-before-read.js";
+import { isDialogType } from "../protocol/dialogs.js";
+import { s } from "../protocol/schema.js";
+import { readProtocol, request, sendOptions } from "./cdp-results.js";
+const attachedSchema = s.object({
+    sessionId: s.string(),
+    targetInfo: s.object({ targetId: s.string(), type: s.string(), subtype: s.optional(s.string()), browserContextId: s.optional(s.string()) }),
+    waitingForDebugger: s.boolean(),
+});
+// Every part but the kind is read leniently, as a page reads it: a dialog Retest could not read would hold the app.
+const openingSchema = s.object({ type: s.string(), message: s.optional(s.string()) });
+const ignore = () => { };
+/**
+ * Attaches an Electron app's first window before its document can show a dialog Retest would not hear, and answers
+ * the dialogs it shows until its page takes them over with `handOver`. Every other page the app opens is let run at
+ * once and let go, as a test reaches only the first window.
+ */
+export class ElectronWindowWatch {
+    #connection;
+    #window = Promise.withResolvers();
+    #answered = [];
+    #taken = false;
+    #stopAnswering;
+    constructor(connection) {
+        this.#connection = connection;
+        connection.on('Target.attachedToTarget', (params) => this.#attached(params));
+    }
+    /**
+     * Asks the app to attach every page it has and hold every new one. Call it before any other command, so it is the
+     * first the app reads; it settles once the app answered, within the deadline.
+     */
+    start(deadline) {
+        const params = { autoAttach: true, waitForDebuggerOnStart: true, flatten: true, filter: [{ type: 'page' }] };
+        return request(this.#connection, 'Target.setAutoAttach', params, s.object({}), sendOptions(deadline)).then(ignore);
+    }
+    /** The first window, once attached; undefined when the deadline passes or the app goes first. */
+    async first(deadline) {
+        const timer = new AbortController();
+        const ended = Promise.withResolvers();
+        const stopListening = this.#connection.onDisconnect(() => ended.resolve(undefined));
+        if (this.#connection.closeReason !== undefined)
+            ended.resolve(undefined);
+        const expired = waitUntilDeadline(deadline, timer.signal).then(() => undefined, () => undefined);
+        try {
+            return await Promise.race([this.#window.promise, ended.promise, expired]);
+        }
+        finally {
+            timer.abort();
+            stopListening();
+        }
+    }
+    /**
+     * Stops answering the first window's dialogs, and gives every dialog answered so far, in order. The page that takes
+     * the window over answers and tells every dialog from then on.
+     */
+    handOver() {
+        this.#stopAnswering?.();
+        this.#stopAnswering = undefined;
+        return [...this.#answered];
+    }
+    // The app's first plain page is the test's. A page held as it opened is let run and let go; a page attached without
+    // being held, as one open before the watch began, is left as it is.
+    #attached(params) {
+        const { sessionId, targetInfo, waitingForDebugger } = readProtocol(attachedSchema, params, { method: 'Target.attachedToTarget' });
+        if (!this.#taken && targetInfo.type === 'page' && targetInfo.subtype === undefined) {
+            this.#take(sessionId, { targetId: targetInfo.targetId, browserContextId: targetInfo.browserContextId ?? '' }, waitingForDebugger);
+            return;
+        }
+        if (!waitingForDebugger)
+            return;
+        this.#connection.adopt(sessionId).send('Runtime.runIfWaitingForDebugger').catch(ignore);
+        this.#connection.send('Target.detachFromTarget', { sessionId }).catch(ignore);
+    }
+    // The session is taken on while its attach is handled, so none of its events comes first. The Page domain goes on
+    // before the window may run, and a held window is let run only after it.
+    #take(sessionId, target, held) {
+        this.#taken = true;
+        const session = this.#connection.adopt(sessionId);
+        this.#stopAnswering = session.on('Page.javascriptDialogOpening', (params) => this.#answer(session, params));
+        session.send('Page.enable').catch(ignore);
+        if (held)
+            session.send('Runtime.runIfWaitingForDebugger').catch(ignore);
+        this.#window.resolve({ session, ...target });
+    }
+    // Dismissed, or accepted for a beforeunload, as a page answers a dialog nothing waited for.
+    #answer(session, params) {
+        const { type, message = '' } = readProtocol(openingSchema, params, { method: 'Page.javascriptDialogOpening', sessionId: session.id });
+        const kind = isDialogType(type) ? type : 'alert';
+        const accept = kind === 'beforeunload';
+        this.#answered.push({ type: kind, message, answered: accept ? 'accepted' : 'dismissed', during: false });
+        session.send('Page.handleJavaScriptDialog', { accept }).catch(ignore);
+    }
+}

package/dist/browser/electron.d.ts

@@ -1,9 +1,11 @@
 import type { FrameSource } from '../media/capture.ts';
 import type { RecordIdentity } from '../protocol/identity.ts';
-import type { SessionIdentity } from './contract.ts';
+import type { RequestResult, SessionIdentity } from './contract.ts';
+import type { DialogArming, DialogReply, UnwaitedDialog } from './dialogs.ts';
+import type { PopupArming } from './popups.ts';
 import type { CdpSession } from './cdp/session.ts';
 import type { PipeStreams, Transport } from './cdp/transport.ts';
-import type { BrowserCommand, DispatchedCommand, NewPageOptions, OwnedBrowser, OutputRedactor, PageNavigation, PageReading, SessionRuntime, TextQuery, WebRuntimeIdentity, WebSession } from './contract.ts';
+import type { BrowserCommand, DispatchedCommand, FilesCapability, NewPageOptions, OwnedBrowser, OutputRedactor, PageNavigation, PageReading, SessionRuntime, TextQuery, WebRuntimeIdentity, WebSession } from './contract.ts';
 import type { DiagnosticCollection, DiagnosticSink } from '../diagnostics/observations.ts';
 import type { DiagnosticScope } from '../protocol/diagnostics.ts';
 import type { CommandResult } from '../protocol/commands.ts';
@@ -11,6 +13,7 @@ import type { StorageState } from '../protocol/storage-state.ts';
 import { Deadline } from '../protocol/deadline.ts';
 import { CdpConnection } from './cdp/connection.ts';
 import { LaunchError } from './contract.ts';
+import { type RouteRemoval } from './routes.ts';
 /** How to launch an Electron app. Every path is absolute. */
 export type ElectronLaunchOptions = {
     /** The Electron binary, inside Electron.app on macOS. */
@@ -168,6 +171,8 @@ export declare class ElectronWindowSession implements WebSession {
     #private;
     constructor(parts: ElectronWindowParts);
     get url(): string | undefined;
+    /** The window's file pickers, caught as a browser's page catches them. The app saves its downloads its own way. */
+    get files(): FilesCapability | undefined;
     execute(command: BrowserCommand, timeoutMs: number, signal?: AbortSignal, commandToken?: number): Promise<CommandResult>;
     identify(session: SessionIdentity): void;
     frameSource(identity: RecordIdentity): FrameSource;
@@ -176,6 +181,12 @@ export declare class ElectronWindowSession implements WebSession {
     screenshot(timeoutMs: number): Promise<Uint8Array>;
     readPage(queries: readonly TextQuery[], timeoutMs: number): Promise<PageReading>;
     onNavigation(listener: (navigation: PageNavigation) => void): () => void;
+    armDialog(timeoutMs: number, signal?: AbortSignal): DialogArming;
+    answerDialog(id: string, reply: DialogReply, timeoutMs: number): Promise<RequestResult>;
+    onUnwaitedDialog(listener: (dialog: UnwaitedDialog) => void): () => void;
+    armPopup(): Promise<PopupArming>;
+    addRoute(): Promise<RequestResult>;
+    removeRoute(): Promise<RouteRemoval>;
     collectDiagnostics(sink: DiagnosticSink, timeoutMs: number): Promise<DiagnosticCollection>;
     captureState(_timeoutMs: number): Promise<StorageState>;
     /** Quits the app, which the window belongs to. */

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

@@ -1 +1 @@
-{"version":3,"file":"electron.d.ts","sourceRoot":"","sources":["../../src/browser/electron.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"electron.d.ts","sourceRoot":"","sources":["../../src/browser/electron.ts"],"names":[],"mappings":"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"}

package/dist/browser/electron.js

@@ -17,9 +17,13 @@ import { readProtocol, request, sendOptions } from "./cdp-results.js";
 import { ChromiumProcess } from "./chromium-process.js";
 import { closeGraceMs, LaunchError } from "./contract.js";
 import { worldName } from "./isolated-world.js";
+import { ElectronWindowWatch } from "./electron-window-watch.js";
 import { describeDiagnostic, handshake, launchOutput, logLength, logWriter } from "./launch.js";
 import { Listeners } from "./listeners.js";
+import { browserCommandLocators, framesUnreached } from "./frames.js";
 import { ChromiumPage } from "./page.js";
+import { keepFocus } from "./popups.js";
+import { routesRefused } from "./routes.js";
 import { changeScript } from "./page-scripts.js";
 import { createTemporaryProfile, removeStaleProfiles } from "./profiles.js";
 import { explainStartFailure } from "./start-failure.js";
@@ -85,8 +89,10 @@ export async function launchElectron(options, timeoutMs = launchTimeoutMs, trans
         // Every command Retest sends names its own timeout; the launch budget bounds any that would not.
         connection = new CdpConnection(transport(child.pipe), { timeoutMs, onDiagnostic: (diagnostic) => log(describeDiagnostic(diagnostic)) });
         const windows = new AppWindows(connection, startedAt, log);
-        const version = await handshake(connection, deadline);
-        // Checked before any window is reached, so a browser given in place of Electron is refused at once.
+        // The watch's request goes first, so the first window's dialogs are heard from its first document on.
+        const watch = new ElectronWindowWatch(connection);
+        const [, version] = await Promise.all([watch.start(deadline), handshake(connection, deadline)]);
+        // Checked before any window is set up as a page, so a browser given in place of Electron is refused at once.
         const electron = await readElectronVersion(executable, version.userAgent);
         if (electron === undefined)
             throw new NotElectronError(executable);
@@ -95,10 +101,18 @@ export async function launchElectron(options, timeoutMs = launchTimeoutMs, trans
         windows.alreadyOpen(targetInfos.map((target) => target.targetId));
         await request(connection, 'Target.setDiscoverTargets', { discover: true }, s.object({}), sendOptions(deadline));
         const first = await windows.first(deadline);
-        const session = await connection.attach(first.targetId, sendOptions(deadline));
+        const attached = await watch.first(deadline);
+        if (attached === undefined)
+            throw new NoWindowError(deadline.budgetMs);
+        const { session } = attached;
         const onListenerError = (error) => log(`a listener failed: ${errorMessage(error)}`);
-        const pageOptions = { connection, session, browserContextId: first.browserContextId, onListenerError };
-        const page = await ChromiumPage.open({ ...pageOptions, baseUrl: undefined, emulation: undefined, restoredOrigins: [], proxyServer: undefined }, deadline);
+        const pageOptions = { connection, session, browserContextId: attached.browserContextId === '' ? first.browserContextId : attached.browserContextId, onListenerError };
+        const answeredDialogs = () => watch.handOver();
+        const page = await ChromiumPage.open({ ...pageOptions, baseUrl: undefined, emulation: undefined, restoredOrigins: [], proxyServer: undefined, answeredDialogs }, deadline);
+        // Chromium draws no animation frames for a window another window covers, or one left behind others, and every action
+        // waits on frames to see its element stand still. A window on a test machine is often not in front, so the page is
+        // made to act as focused, as a Chrome page is, which keeps its frames coming.
+        await keepFocus(session, deadline);
         await observeChanges(session, deadline, (note) => {
             windows.note(note);
             log(note);
@@ -350,7 +364,10 @@ class ElectronApp {
     }
     async #close(timeoutMs) {
         this.#closeRequested = true;
-        this.#process.recordDescendants();
+        const graceMs = Math.max(0, Math.min(closeGraceMs, timeoutMs - closeGraceMs));
+        // The app's helpers are read before its pipe closes, without holding the thread, within the allowance `stop` has.
+        const ownershipDeadline = new Deadline(graceMs + 2 * closeGraceMs);
+        await this.#process.recordDescendantsNow(ownershipDeadline);
         const problems = [];
         try {
             this.#connection.close();
@@ -358,8 +375,7 @@ class ElectronApp {
         catch (error) {
             problems.push(`Could not close the Electron app's debugging pipe: ${errorMessage(error)}`);
         }
-        const graceMs = Math.max(0, Math.min(closeGraceMs, timeoutMs - closeGraceMs));
-        problems.push(...await this.#process.stop(graceMs), ...this.#cleanupProblems);
+        problems.push(...await this.#process.stop(graceMs, ownershipDeadline), ...this.#cleanupProblems);
         const { app, target, launch, windowsFile } = this.#named;
         const notes = this.#windows.notes;
         const record = { app, target, launch, pid: this.pid, windows: this.#windows.records, ...(notes.length === 0 ? {} : { notes }) };
@@ -405,6 +421,10 @@ export class ElectronWindowSession {
     get url() {
         return this.#window.url;
     }
+    /** The window's file pickers, caught as a browser's page catches them. The app saves its downloads its own way. */
+    get files() {
+        return this.#window.files;
+    }
     async execute(command, timeoutMs, signal, commandToken) {
         return (await this.dispatch(command, timeoutMs, signal, commandToken)).result;
     }
@@ -419,6 +439,10 @@ export class ElectronWindowSession {
     async dispatch(command, timeoutMs, signal, commandToken) {
         if (command.kind === 'goto')
             return { result: { ok: false, failure: this.#noAddress() }, input: 'not_sent' };
+        // No test has looked inside a frame of an Electron window yet, so a frame there is refused by name.
+        const unreached = framesUnreached(browserCommandLocators(command), `the window of the Electron app ${this.#app}`);
+        if (unreached !== undefined)
+            return { result: { ok: false, failure: unreached }, input: 'not_sent' };
         const answer = await this.#window.dispatch(command, timeoutMs, signal, commandToken);
         if (answer.result.ok || !this.#firstClosed())
             return answer;
@@ -439,6 +463,27 @@ export class ElectronWindowSession {
     onNavigation(listener) {
         return this.#window.onNavigation(listener);
     }
+    // A dialog in the app's first window is handed over and answered as on a browser's page.
+    armDialog(timeoutMs, signal) {
+        return this.#window.armDialog?.(timeoutMs, signal) ?? { ok: false, failure: { class: 'unsupported', message: `The window of the Electron app ${this.#app} cannot hand its dialogs to a test.` } };
+    }
+    answerDialog(id, reply, timeoutMs) {
+        return this.#window.answerDialog?.(id, reply, timeoutMs) ?? Promise.resolve({ ok: false, failure: { class: 'unsupported', message: `The window of the Electron app ${this.#app} cannot answer a dialog for a test.` } });
+    }
+    onUnwaitedDialog(listener) {
+        return this.#window.onUnwaitedDialog?.(listener) ?? (() => undefined);
+    }
+    // A test reaches only the app's first window, so a window the app opens is out of its reach.
+    async armPopup() {
+        return { ok: false, failure: { class: 'unsupported', message: `A test reaches only the first window of the Electron app ${this.#app}, so page.popup() is for a browser's page.` } };
+    }
+    // The app's window holds no route: Retest has not checked how an app's own requests meet the window's Fetch domain.
+    async addRoute() {
+        return { ok: false, failure: routesRefused('in an Electron app') };
+    }
+    async removeRoute() {
+        return { ok: false, failure: routesRefused('in an Electron app') };
+    }
     // The app opens its window as it starts, before any test asks for it, while a browser's page is still blank by then. A
     // window already showing a page once capture runs has had time to log and load what nobody heard. The window itself
     // is asked, after capture started, since the page may have missed the commit of a document that came first.

package/dist/browser/element-queries.d.ts

@@ -1,7 +1,8 @@
 import type { BrowserCommand, DispatchedCommand } from './contract.ts';
 import type { DocumentFacts } from './document-facts.ts';
 import type { Point } from './input.ts';
-import type { InDocument, IsolatedWorld } from './isolated-world.ts';
+import type { Guard } from './input-guard.ts';
+import type { InDocument, PageWorld, WorldArguments } from './isolated-world.ts';
 import type { Observation } from '../protocol/commands.ts';
 import type { Deadline } from '../protocol/deadline.ts';
 import type { EmptyStep, LocatorRecipe } from '../protocol/locator.ts';
@@ -11,10 +12,11 @@ import type { Schema } from '../protocol/schema.ts';
 declare const checks: readonly ["attached", "visible", "enabled", "editable", "stable", "in-view", "hit-target", "focused"];
 /** An actionability check, in the order `prepare` runs them after the element is found. */
 export type Check = (typeof checks)[number];
-declare const unsupportedReasons: readonly ["field", "multiline", "checkable", "radio", "select", "multiple"];
+declare const unsupportedReasons: readonly ["field", "multiline", "checkable", "radio", "select", "multiple", "toggle"];
 /**
  * Why an element cannot take an action at all: not a field `fill` can use, a line break for a one-line field, not a
- * control `check` can use, a radio button to uncheck, not a `<select>`, or a list for a select that takes one.
+ * control `check` can use, a radio button to uncheck, not a `<select>`, a list for a select that takes one, or a
+ * select whose keys would toggle an option, on an engine that sends no such key.
  */
 export type UnsupportedReason = (typeof unsupportedReasons)[number];
 /** One key of a select's plan: a character to type, or `Home`, `ArrowDown` or `Space`, with the modifier that leaves the selection alone. */
@@ -98,7 +100,8 @@ export type Pointer = 'click' | 'tap';
  * `allowedOrigins` are the only origins a `fill` may type into. A `press` names its key as the test wrote it, and how
  * many keys it holds and presses. A `check` or `uncheck` clicks through `pointer`. A `select` names its choices, and
  * `multiple` when the test gave a list; with `typing`, it is one key of the select's plan, which holds `strokes` keys.
- * A `scroll` turns the wheel, and a `hover` moves the mouse.
+ * `toggleRefusal`, on an engine that sends no key that toggles an option, says why: a select that needs one is refused
+ * as soon as it is found, before any check that waits. A `scroll` turns the wheel, and a `hover` moves the mouse.
  */
 export type ActionIntent = {
     multiline: boolean;
@@ -126,9 +129,38 @@ export type ActionIntent = {
     typing?: {
         strokes: number;
     };
+    toggleRefusal?: string;
 });
 /** A look at the page for input that goes to the document, not to an element: a key or the wheel. */
 export type DocumentAction = 'press' | 'scroll';
+/** A look that readied an element, as `prepare` answers. */
+export type ReadyReadiness = Extract<Readiness, {
+    status: 'ready';
+}>;
+/**
+ * A look for an action, in the document it ran in. For an element in a frame, `around` holds the guards the look armed
+ * in the documents around the frame, outermost first.
+ */
+export type Prepared = InDocument<Readiness> & {
+    around?: readonly Guard[];
+};
+/** The pointer input a frame's element passes on to an element inside it, which the documents around the frame guard. */
+export type PointerThrough = Pointer | 'hover' | 'scroll';
+/**
+ * A world in the document of a frame, which finds the frame again by its element for every call. A look there reads
+ * the frame's own document. `missing` says what an error a call threw was found missing: the element of one of the
+ * frames, as an empty step that names that frame, or null when the element is there and its document is not yet;
+ * undefined for any other error. `place` moves the point an action readied in the frame's document to the page's
+ * viewport, where input lands, after it checks the frame in each document around it, and for `pointer` input arms
+ * each of those documents' guards for the frame's element. `pageFacts` reads the page's own address and title.
+ */
+export interface FramedWorld extends PageWorld {
+    /** As `enter`, with each frame on the path brought into view first, as an action brings its element into view. */
+    enterInView<T>(functionDeclaration: string, args: WorldArguments, schema: Schema<T>, deadline: Deadline): Promise<InDocument<T>>;
+    missing(error: unknown): EmptyStep | null | undefined;
+    place(ready: InDocument<ReadyReadiness>, pointer: PointerThrough | null, deadline: Deadline): Promise<Prepared>;
+    pageFacts(deadline: Deadline): Promise<DocumentFacts>;
+}
 /** A CSS selector of a locator's step that the page could not read, with the browser's reason. */
 export type InvalidSelector = {
     step: number;
@@ -146,8 +178,11 @@ export type Observed = {
 } | {
     shadow: string;
 };
-/** Resolves the locator once and reads what an assertion needs, and the page it read it on. */
-export declare function observe(world: IsolatedWorld, locator: LocatorRecipe, deadline: Deadline): Promise<Observed>;
+/**
+ * Resolves the locator once and reads what an assertion needs, and the page it read it on. In a frame whose element
+ * is not there, it reads no match, on the page the frame was looked for in.
+ */
+export declare function observe(world: PageWorld, locator: LocatorRecipe, deadline: Deadline): Promise<Observed>;
 /** One locator's read in a keyed look: its observation, and the key of each element it lists, in the same order. */
 export type KeyedLook = {
     observation: Observation;
@@ -172,7 +207,7 @@ export type KeyedObserved = {
  * listed with the key the document's world keeps for that node. An answer that does not read each locator once, or
  * does not key each element it lists, is not Retest's page function answering, and throws. Sends no input.
  */
-export declare function observeKeyed(world: IsolatedWorld, locators: readonly LocatorRecipe[], deadline: Deadline): Promise<KeyedObserved>;
+export declare function observeKeyed(world: PageWorld, locators: readonly LocatorRecipe[], deadline: Deadline): Promise<KeyedObserved>;
 /**
  * Sends one command through `dispatch` with every look that readies its element pinned to the node `key` names: a
  * look whose locator finds another node answers `moved`, which fails the command at once with no input sent. A command
@@ -193,9 +228,10 @@ export declare function pinnedKey(): string | undefined;
  * Resolves the locator once and runs the checks an action needs, readying a field for `fill` and focusing the
  * element for `press`, or for one key of a `select`'s plan. Also names the document it looked at, which holds the
  * guard a ready element armed. A `select` that is not yet typing is only checked here, and planned. Inside
- * `dispatchPinned` the one match must be the pinned node.
+ * `dispatchPinned` the one match must be the pinned node. In a frame, the checks run in the frame's document, and the
+ * point to act at is then placed in the page's viewport; a frame whose element is not there is missing, as an element is.
  */
-export declare function prepare(world: IsolatedWorld, locator: LocatorRecipe, intent: ActionIntent, deadline: Deadline): Promise<InDocument<Readiness>>;
+export declare function prepare(world: PageWorld, locator: LocatorRecipe, intent: ActionIntent, deadline: Deadline): Promise<Prepared>;
 /** Whether a select holds exactly the options its choices name, the labels of those it holds, and the page it is on. */
 export type Selection = {
     status: 'selected' | 'other' | 'lost';
@@ -226,12 +262,12 @@ export type TypedSelect = {
  * undefined once that document has gone: a select another document holds is never read in its place. Inside
  * `dispatchPinned` it reads the pinned select only, and another in its place is `lost`. Sends no input.
  */
-export declare function readSelection(world: IsolatedWorld, { locator, choices, document }: TypedSelect, deadline: Deadline): Promise<Selection | undefined>;
+export declare function readSelection(world: PageWorld, { locator, choices, document }: TypedSelect, deadline: Deadline): Promise<Selection | undefined>;
 /**
  * Whether `document` set off for another document since the arming `token` began, or has gone already. A select's
  * next key goes only into a document that is staying. Sends no input.
  */
-export declare function pageSetOff(world: IsolatedWorld, { document, token }: {
+export declare function pageSetOff(world: PageWorld, { document, token }: {
     document: number;
     token: number;
 }, deadline: Deadline): Promise<boolean>;
@@ -240,14 +276,14 @@ export declare function pageSetOff(world: IsolatedWorld, { document, token }: {
  * to whatever holds the focus there, with the keys it holds and presses, or the wheel at the centre of the viewport.
  * Ready as `prepare` is, in that document.
  */
-export declare function armDocument(world: IsolatedWorld, action: DocumentAction, strokes: number, deadline: Deadline): Promise<InDocument<Extract<Readiness, {
+export declare function armDocument(world: PageWorld, action: DocumentAction, strokes: number, deadline: Deadline): Promise<InDocument<Extract<Readiness, {
     status: 'ready';
 }>>>;
 /**
- * Whether the one element the locator finds is checked, or null when no single such control is there. Inside
- * `dispatchPinned` it reads the pinned element only, and another in its place is null.
+ * Whether the one element the locator finds is checked, or null when no single such control is there, a frame it is
+ * in included. Inside `dispatchPinned` it reads the pinned element only, and another in its place is null.
  */
-export declare function readChecked(world: IsolatedWorld, locator: LocatorRecipe, deadline: Deadline): Promise<boolean | null>;
+export declare function readChecked(world: PageWorld, locator: LocatorRecipe, deadline: Deadline): Promise<boolean | null>;
 /**
  * An action as failure messages name it, the way a test reads: a press names its key, a select its choices, and
  * a key for the page's keyboard or a wheel for the page has no element.

package/dist/browser/element-queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"element-queries.d.ts","sourceRoot":"","sources":["../../src/browser/element-queries.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"element-queries.d.ts","sourceRoot":"","sources":["../../src/browser/element-queries.ts"],"names":[],"mappings":"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"}

package/dist/browser/element-queries.js

@@ -9,7 +9,7 @@ import { isGoneContext } from "./isolated-world.js";
 import { locatorArguments, locatorsArguments } from "./locate.js";
 import { armDocumentFunction, checkedFunction, keyedObserveFunction, observeFunction, prepareFunction, selectionFunction, setOffFunction } from "./page-scripts.js";
 const checks = ['attached', 'visible', 'enabled', 'editable', 'stable', 'in-view', 'hit-target', 'focused'];
-const unsupportedReasons = ['field', 'multiline', 'checkable', 'radio', 'select', 'multiple'];
+const unsupportedReasons = ['field', 'multiline', 'checkable', 'radio', 'select', 'multiple', 'toggle'];
 const pageFacts = documentFactsSchema;
 const planSchema = s.object({
     quietMs: s.number({ integer: true, min: 0 }),
@@ -43,16 +43,42 @@ const readinessSchema = s.discriminatedUnion('status', [
     s.object({ status: s.literal('unchanged'), page: pageFacts }),
     readySchema,
 ]);
+// The context of a look that found no frame, which has no document. Nothing reads the context of an unready look.
+const noDocument = -1;
+function framedWorld(world) {
+    return isFramed(world) ? world : undefined;
+}
+// Only a frame's world places a point, and it answers the rest of `FramedWorld` with it.
+function isFramed(world) {
+    return 'place' in world;
+}
+// What a look reads when a frame of its locator is not there: no match, and the frame that kept nothing.
+function unseen(empty) {
+    const missing = empty === null ? {} : { emptyStep: empty };
+    return { count: 0, visible: null, text: null, value: null, checked: null, enabled: null, items: [], itemsTruncated: false, ...missing };
+}
 const invalidSchema = s.object({ step: s.number({ integer: true, min: 0 }), message: s.string() });
 const observedSchema = s.union([
     s.object({ observation: observationSchema, page: pageFacts }),
     s.object({ invalid: invalidSchema }),
     s.object({ shadow: s.string() }),
 ]);
-/** Resolves the locator once and reads what an assertion needs, and the page it read it on. */
+/**
+ * Resolves the locator once and reads what an assertion needs, and the page it read it on. In a frame whose element
+ * is not there, it reads no match, on the page the frame was looked for in.
+ */
 export async function observe(world, locator, deadline) {
-    const observed = await world.call(observeFunction, locatorArguments(locator, [observedItemLimit]), observedSchema, deadline);
-    return 'observation' in observed ? { observation: observed.observation, page: pageFactsOf(observed.page) } : observed;
+    try {
+        const observed = await world.call(observeFunction, locatorArguments(locator, [observedItemLimit]), observedSchema, deadline);
+        return 'observation' in observed ? { observation: observed.observation, page: pageFactsOf(observed.page) } : observed;
+    }
+    catch (error) {
+        const framed = framedWorld(world);
+        const missing = framed?.missing(error);
+        if (framed === undefined || missing === undefined)
+            throw error;
+        return { observation: unseen(missing), page: pageFactsOf(await framed.pageFacts(deadline)) };
+    }
 }
 const keyedSchema = s.union([
     s.object({ reads: s.array(s.object({ observation: observationSchema, keys: s.array(s.string()) })), page: pageFacts }),
@@ -65,7 +91,17 @@ const keyedSchema = s.union([
  * does not key each element it lists, is not Retest's page function answering, and throws. Sends no input.
  */
 export async function observeKeyed(world, locators, deadline) {
-    const observed = await world.call(keyedObserveFunction, locatorsArguments(locators, [observedItemLimit]), keyedSchema, deadline);
+    let observed;
+    try {
+        observed = await world.call(keyedObserveFunction, locatorsArguments(locators, [observedItemLimit]), keyedSchema, deadline);
+    }
+    catch (error) {
+        const framed = framedWorld(world);
+        const missing = framed?.missing(error);
+        if (framed === undefined || missing === undefined)
+            throw error;
+        return { reads: locators.map(() => ({ observation: unseen(missing), keys: [] })), page: pageFactsOf(await framed.pageFacts(deadline)) };
+    }
     if ('invalid' in observed)
         return { invalid: observed.invalid, locator: observed.query };
     if ('shadow' in observed)
@@ -108,12 +144,46 @@ export function pinnedKey() {
  * Resolves the locator once and runs the checks an action needs, readying a field for `fill` and focusing the
  * element for `press`, or for one key of a `select`'s plan. Also names the document it looked at, which holds the
  * guard a ready element armed. A `select` that is not yet typing is only checked here, and planned. Inside
- * `dispatchPinned` the one match must be the pinned node.
+ * `dispatchPinned` the one match must be the pinned node. In a frame, the checks run in the frame's document, and the
+ * point to act at is then placed in the page's viewport; a frame whose element is not there is missing, as an element is.
  */
-export function prepare(world, locator, intent, deadline) {
+export async function prepare(world, locator, intent, deadline) {
     const pinned = pinnedElement.getStore();
     const asked = pinned === undefined ? pageIntent(intent) : { ...pageIntent(intent), element: pinned };
-    return world.enter(prepareFunction, locatorArguments(locator, [asked]), readinessSchema, deadline);
+    const framed = framedWorld(world);
+    if (framed === undefined)
+        return world.enter(prepareFunction, locatorArguments(locator, [asked]), readinessSchema, deadline);
+    let seen;
+    try {
+        seen = await framed.enterInView(prepareFunction, locatorArguments(locator, [asked]), readinessSchema, deadline);
+    }
+    catch (error) {
+        const missing = framed.missing(error);
+        if (missing === undefined)
+            throw error;
+        return { value: { status: 'missing', empty: missing }, context: noDocument };
+    }
+    const { value, context } = seen;
+    // A key goes to the focus, which the frame took with the element; only a point is placed in the page.
+    return value.status === 'ready' && value.point !== null ? framed.place({ value, context }, pointerThrough(intent), deadline) : seen;
+}
+// The pointer input an action sends, which goes through each frame's element at its point; null for keys and typing,
+// which go to the focus.
+function pointerThrough(intent) {
+    switch (intent.action) {
+        case 'click':
+        case 'tap':
+        case 'hover':
+        case 'scroll':
+            return intent.action;
+        case 'check':
+        case 'uncheck':
+            return intent.pointer;
+        case 'fill':
+        case 'press':
+        case 'select':
+            return null;
+    }
 }
 export const pageSelectionSchema = s.object({
     status: s.enum(['selected', 'other', 'lost']),
@@ -166,11 +236,18 @@ export function armDocument(world, action, strokes, deadline) {
     return world.enter(armDocumentFunction, [action, strokes], readySchema, deadline);
 }
 /**
- * Whether the one element the locator finds is checked, or null when no single such control is there. Inside
- * `dispatchPinned` it reads the pinned element only, and another in its place is null.
+ * Whether the one element the locator finds is checked, or null when no single such control is there, a frame it is
+ * in included. Inside `dispatchPinned` it reads the pinned element only, and another in its place is null.
  */
-export function readChecked(world, locator, deadline) {
-    return world.call(checkedFunction, locatorArguments(locator, [], pinnedKey()), s.nullable(s.boolean()), deadline);
+export async function readChecked(world, locator, deadline) {
+    try {
+        return await world.call(checkedFunction, locatorArguments(locator, [], pinnedKey()), s.nullable(s.boolean()), deadline);
+    }
+    catch (error) {
+        if (framedWorld(world)?.missing(error) === undefined)
+            throw error;
+        return null;
+    }
 }
 /**
  * An action as failure messages name it, the way a test reads: a press names its key, a select its choices, and
@@ -208,7 +285,9 @@ function pageIntent(intent) {
             return { action: 'check', checked: intent.action === 'check', pointer: intent.pointer };
         case 'select': {
             const typing = intent.typing === undefined ? {} : { typing: true, strokes: intent.typing.strokes };
-            return { action: 'select', choices: intent.choices, multiple: intent.multiple, ...typing };
+            // The page needs only to know that no toggle goes; the reason stays here, for the failure.
+            const toggles = intent.toggleRefusal === undefined ? {} : { toggles: false };
+            return { action: 'select', choices: intent.choices, multiple: intent.multiple, ...typing, ...toggles };
         }
         case 'press':
             return { action: 'press', strokes: intent.strokes };

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

@@ -1 +1 @@
-{"version":3,"file":"emulation.d.ts","sourceRoot":"","sources":["../../src/browser/emulation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAMvD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAMjH"}
+{"version":3,"file":"emulation.d.ts","sourceRoot":"","sources":["../../src/browser/emulation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAMvD;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAUjH"}