diff --git a/.changeset/last-read-grace.md b/.changeset/last-read-grace.md new file mode 100644 index 0000000000..80b11c58cd --- /dev/null +++ b/.changeset/last-read-grace.md @@ -0,0 +1,5 @@ +--- +'e2e': patch +--- + +`waitFor`, `expect` on a locator, and `toHaveScreenshot` give their last read extra time past the timeout, as long as their slowest read so far, so a screen that shows up during a slow last read still passes. diff --git a/.changeset/mobile-reads-budget.md b/.changeset/mobile-reads-budget.md new file mode 100644 index 0000000000..be06c4028f --- /dev/null +++ b/.changeset/mobile-reads-budget.md @@ -0,0 +1,5 @@ +--- +'@e2e-dev/mobile': patch +--- + +Snapshots and screenshots now get the step's timeout, so a device that stops answering fails the step instead of holding it until the test timeout. Requires `e2e` 0.21.4 or later. diff --git a/docs/mobile.mdx b/docs/mobile.mdx index ae894037e3..b16285ec6e 100644 --- a/docs/mobile.mdx +++ b/docs/mobile.mdx @@ -732,8 +732,13 @@ message and hint, never `LAUNCH_TIMEOUT`, `ACTION_FAILED`, or `back` gets its `timeout` (default `actionTimeout`). If the device doesn't answer in time, the step fails with `ACTION_FAILED` and isn't retried: the input may have landed. A `longPress` that holds at least as long as the -time left is refused before it's sent; raise its `timeout`. Finding the -element isn't cut off, so a missing one still fails as `LOCATOR_NOT_FOUND`. +time left is refused before it's sent; raise its `timeout`. Snapshots and +screenshots get the same timeout, so a device that stops answering fails the +step with `ACTION_FAILED` instead of holding it until the test timeout. +`waitFor`, `expect`, and `toHaveScreenshot` give their last snapshot extra +time, as long as their slowest one so far, so a screen that shows up during +it still passes. An element that never shows up fails as +`LOCATOR_NOT_FOUND`, or `ASSERTION_FAILED` for `expect`. ```bash npm diff --git a/docs/reference/engine.mdx b/docs/reference/engine.mdx index 56ae003b55..41edae4e7e 100644 --- a/docs/reference/engine.mdx +++ b/docs/reference/engine.mdx @@ -313,7 +313,11 @@ export interface OperationContext { * abort at `timeoutMs`: bound each call by that budget yourself. */ readonly signal: AbortSignal; - /** Remaining operation budget when the call starts. */ + /** + * Remaining operation budget when the call starts. A waiting call's last + * locate or read can get more than its deadline leaves: as long as the + * slowest one it has seen. + */ readonly timeoutMs: number; /** The run id. */ readonly runId: string; @@ -1409,8 +1413,9 @@ export const RETRYABLE_ENGINE_ERROR_CODES: ReadonlySet = new Se #### Timeouts at a deadline -An `OPERATION_TIMEOUT` on a locate or read that started with under 100 ms of -a waiting call's deadline left, after one that completed, ends the wait +An `OPERATION_TIMEOUT` on a locate or read that started with under 100 ms, or +under its slowest completed locate or read, of a waiting call's deadline left, +after one that completed, ends the wait instead: | Waiting call | Fails with | diff --git a/packages/e2e/src/engine/contract.ts b/packages/e2e/src/engine/contract.ts index fc1f815568..6aa14b91ba 100644 --- a/packages/e2e/src/engine/contract.ts +++ b/packages/e2e/src/engine/contract.ts @@ -32,7 +32,11 @@ export interface OperationContext { * abort at `timeoutMs`: bound each call by that budget yourself. */ readonly signal: AbortSignal; - /** Remaining operation budget when the call starts. */ + /** + * Remaining operation budget when the call starts. A waiting call's last + * locate or read can get more than its deadline leaves: as long as the + * slowest one it has seen. + */ readonly timeoutMs: number; /** The run id. */ readonly runId: string; diff --git a/packages/e2e/src/expect/async.ts b/packages/e2e/src/expect/async.ts index 579d38fb2f..4f022e3599 100644 --- a/packages/e2e/src/expect/async.ts +++ b/packages/e2e/src/expect/async.ts @@ -14,7 +14,7 @@ import { type TextPattern, } from '../internal/text.ts'; import { isValueControl } from '../internal/roles.ts'; -import { Deadline, pollCondition } from '../internal/time.ts'; +import { pollReads, type ReadWindow } from '../internal/time.ts'; import { SampleHistory } from './samples.ts'; import { attributeOf, denySecureRead, isNodeVisible } from '../locator/engine.ts'; import { describeExpression } from '../locator/expression.ts'; @@ -173,12 +173,13 @@ class AsyncExpectationImpl implements AsyncExpectation { let lastSample: Sample = { count: 0, node: null, nodes: [] }; const samples = new SampleHistory('expect', (text) => engine.redact(text)); await samples.record(engine, () => - pollCondition({ + pollReads({ deadline, + reads: engine.reads(deadline), signal: engine.signal, negated: this.negated, - evaluate: async () => { - const sample = await this.sample(spec, deadline); + evaluate: async (reads) => { + const sample = await this.sample(spec, reads); lastSample = sample; if (spec.readsWithheld === true) { denySecureRead(sample.node === null ? sample.nodes : [sample.node], this.label); @@ -221,18 +222,18 @@ class AsyncExpectationImpl implements AsyncExpectation { return spec.evaluableNode?.(sample.node) ?? true; } - private async sample(spec: MatcherSpec, deadline: Deadline): Promise { + private async sample(spec: MatcherSpec, reads: ReadWindow): Promise { const { engine } = this.internals.context; if (spec.wholeSet === 'read') { - const nodes = await engine.readAllNow(this.internals.expression, deadline); + const nodes = await engine.readAllNow(this.internals.expression, reads); return { count: nodes.length, node: null, nodes }; } if (spec.wholeSet === true) { - const refs = await engine.resolveNow(this.internals.expression, deadline); + const refs = await engine.resolveNow(this.internals.expression, reads); return { count: refs.length, node: null, nodes: [] }; } const missingFrame = spec.evaluableWithoutNode === true ? 'empty' : 'wait'; - const { node, count } = await engine.tryRead(this.internals.expression, deadline, missingFrame); + const { node, count } = await engine.tryRead(this.internals.expression, reads, missingFrame); return { count, node, nodes: [] }; } diff --git a/packages/e2e/src/expect/screenshot-capture.ts b/packages/e2e/src/expect/screenshot-capture.ts index 94c74dc58e..08c9f384e7 100644 --- a/packages/e2e/src/expect/screenshot-capture.ts +++ b/packages/e2e/src/expect/screenshot-capture.ts @@ -8,7 +8,7 @@ import type { LocatorExpression } from '../engine/surface.ts'; import { ConfigurationError, isE2EError } from '../internal/errors.ts'; import { clipBox, cropImage, decodePng, fillBoxes, resampleImage, type ImageBox, type RgbaImage } from '../internal/image.ts'; -import { isOperationTimeout, type Deadline } from '../internal/time.ts'; +import { isOperationTimeout, type ReadWindow } from '../internal/time.ts'; import { isNodeVisible } from '../locator/engine.ts'; import { describeExpression } from '../locator/expression.ts'; import type { ScreenContext } from '../locator/screen.ts'; @@ -33,40 +33,40 @@ export type Capture = { readonly image: RgbaImage } | { readonly missing: string * a capture the deadline cut short: the call then fails on what the * captures before it showed. */ -export function screenshotCapturer(context: ScreenContext, request: CaptureRequest, deadline: Deadline): () => Promise { +export function screenshotCapturer(context: ScreenContext, request: CaptureRequest, reads: ReadWindow): () => Promise { const { engine } = context; const state = { scrolled: !engine.session.actions.has('scrollIntoView') }; return async () => { try { - return await captureOnce(context, request, deadline, state); + return await captureOnce(context, request, reads, state); } catch (cause) { - if (deadline.expired() && isOperationTimeout(cause)) return { missing: 'the last screenshot ran past the timeout' }; + if (reads.deadline.expired() && isOperationTimeout(cause)) return { missing: 'the last screenshot ran past the timeout' }; throw cause; } }; } /** One capture; `state.scrolled` records that the subject was scrolled into view. */ -async function captureOnce(context: ScreenContext, request: CaptureRequest, deadline: Deadline, state: { scrolled: boolean }): Promise { +async function captureOnce(context: ScreenContext, request: CaptureRequest, reads: ReadWindow, state: { scrolled: boolean }): Promise { const { engine } = context; const shown = request.subject === undefined ? 'screen' : describeExpression(request.subject); let box: ImageBox | undefined; if (request.subject !== undefined) { - let { node } = await engine.tryRead(request.subject, deadline); + let { node } = await engine.tryRead(request.subject, reads); if (node !== null && !state.scrolled) { try { - await engine.performUntil(request.subject, { kind: 'scrollIntoView' }, deadline); + await engine.performUntil(request.subject, { kind: 'scrollIntoView' }, reads.deadline); } catch (cause) { if (!isE2EError(cause) || cause.code !== 'LOCATOR_NOT_FOUND') throw cause; } state.scrolled = true; - ({ node } = await engine.tryRead(request.subject, deadline)); + ({ node } = await engine.tryRead(request.subject, reads)); } if (node === null) return { missing: `no node matches ${shown}` }; if (!isNodeVisible(node) || node.rect === undefined) return { missing: `${shown} is not visible` }; box = node.rect; } - const observation = await engine.session.observe(engine.operationWithin(deadline), { pixels: true, comparable: true }); + const observation = await reads.read((timeoutMs) => engine.session.observe(engine.readOperation(timeoutMs), { pixels: true, comparable: true })); if (observation.pixels === undefined) return { missing: 'the engine returned no screenshot' }; if (!pixelsProvenMasked(observation.redaction)) { throw new ConfigurationError('POLICY_DENIED', `${request.api} could not prove every secure field on screen was masked, so the screenshot is not kept`); @@ -85,7 +85,7 @@ async function captureOnce(context: ScreenContext, request: CaptureRequest, dead if (request.masks.length === 0) return { image }; const boxes: ImageBox[] = []; for (const mask of request.masks) { - for (const node of await engine.readAllNow(mask, deadline)) { + for (const node of await engine.readAllNow(mask, reads)) { if (isNodeVisible(node) && node.rect !== undefined) boxes.push({ ...node.rect, x: node.rect.x - origin.x, y: node.rect.y - origin.y }); } } diff --git a/packages/e2e/src/expect/screenshot.ts b/packages/e2e/src/expect/screenshot.ts index e1c5a339db..ba64ce5159 100644 --- a/packages/e2e/src/expect/screenshot.ts +++ b/packages/e2e/src/expect/screenshot.ts @@ -11,7 +11,7 @@ import type { LocatorExpression } from '../engine/surface.ts'; import { writeFileAtomic } from '../internal/atomic-write.ts'; import { TestError } from '../internal/errors.ts'; import { compareImages, decodePng, encodePng, type ImageComparison, type RgbaImage } from '../internal/image.ts'; -import { pollCondition, type Deadline } from '../internal/time.ts'; +import { pollReads, type Deadline, type ReadWindow } from '../internal/time.ts'; import { describeExpression } from '../locator/expression.ts'; import type { ScreenContext } from '../locator/screen.ts'; import type { ScreenshotContext } from '../run/screenshots.ts'; @@ -32,6 +32,7 @@ interface Run { readonly api: string; readonly call: ScreenshotCall; readonly stored: Stored; + readonly reads: ReadWindow; readonly capture: () => Promise; } @@ -75,8 +76,9 @@ export async function expectScreenshot( const label = `${subject === undefined ? 'screen' : describeExpression(subject)} vs ${call.stem}.png`; await context.steps.run('assertion', api, label, async () => { const deadline = context.engine.deadline(call.timeout ?? context.engine.assertionTimeout); - const capture = screenshotCapturer(context, { api, subject, masks: call.masks, maskColor: call.maskColor }, deadline); - const run: Run = { context, store, api, call, stored, capture }; + const reads = context.engine.reads(deadline); + const capture = screenshotCapturer(context, { api, subject, masks: call.masks, maskColor: call.maskColor }, reads); + const run: Run = { context, store, api, call, stored, reads, capture }; const expected = existsSync(file) ? readStored(api, stored) : undefined; if (expected !== undefined && (negated || !store.update) && store.written.has(file)) { throw failure(api, `${stored.shown} was written earlier in this run and is not reviewed yet: look at it, commit it, and run again`, stored, 'unreviewed stored screenshot'); @@ -107,8 +109,9 @@ async function matchOrSettle(run: Run, expected: RgbaImage | undefined, deadline let unsettled: readonly [RgbaImage, RgbaImage] | undefined; let settled: RgbaImage | undefined; let captures = 0; - await pollCondition({ + await pollReads({ deadline, + reads: run.reads, signal: run.context.engine.signal, negated: false, evaluate: async () => { @@ -181,8 +184,9 @@ async function expectDifferent(run: Run, expected: RgbaImage | undefined, deadli } let compared = false; let missing: string | undefined; - await pollCondition({ + await pollReads({ deadline, + reads: run.reads, signal: run.context.engine.signal, negated: true, evaluate: async () => { diff --git a/packages/e2e/src/internal/time.ts b/packages/e2e/src/internal/time.ts index 1fb4d22d51..e92287f19d 100644 --- a/packages/e2e/src/internal/time.ts +++ b/packages/e2e/src/internal/time.ts @@ -75,15 +75,44 @@ export function budgetText(ms: number): string { export const POLL_INTERVAL_MS = 100; /** - * Whether `cause` is a read a wait's deadline cut off: an operation timeout - * of a read that started with less than one poll tick of the wait left, so - * it timed out because the wait did, not because the app stopped answering. - * A read that started with more and still timed out hung, and its timeout is - * the failure. Reads the engine error a locator failure wraps as well as a - * bare one. + * The reads of one wait. Each engine read runs on the time left before the + * wait's deadline plus the longest read the wait has finished, capped by + * `cap` (the running phase's deadline), so a slow last read still finishes. + * Without a cap, reads end at the deadline. */ -export function cutOffAtDeadline(cause: unknown, startedWithMs: number): boolean { - return startedWithMs < POLL_INTERVAL_MS && isOperationTimeout(cause); +export class ReadWindow { + private slowestMs = 0; + + constructor( + readonly deadline: Deadline, + private readonly cap: Deadline = deadline, + ) {} + + /** The budget for an engine read starting now, never under 1 ms. */ + timeoutMs(): number { + const now = Date.now(); + return Math.max(1, Math.min(this.cap.remaining(now), this.deadline.remaining(now) + this.slowestMs)); + } + + /** Runs one engine read on `timeoutMs()`, timing it when it answers. */ + async read(call: (timeoutMs: number) => Promise): Promise { + const startedAt = Date.now(); + const value = await call(this.timeoutMs()); + this.slowestMs = Math.max(this.slowestMs, Date.now() - startedAt); + return value; + } + + /** + * Whether `cause` is a read the deadline cut off: an operation timeout of a + * read that started with less than one poll tick, or the longest read this + * wait finished, of the deadline left, so it timed out because the wait + * did, not because the app stopped answering. A read that started with + * more and still timed out hung, and its timeout is the failure. Reads the + * engine error a locator failure wraps as well as a bare one. + */ + cutOff(cause: unknown, startedWithMs: number): boolean { + return startedWithMs < Math.max(POLL_INTERVAL_MS, this.slowestMs) && isOperationTimeout(cause); + } } /** Whether `cause` is the engine's `OPERATION_TIMEOUT`, bare or wrapped by the locator failure it was translated into. */ @@ -110,6 +139,13 @@ export interface PollConditionOptions { onTimeout(cause?: unknown): Error | Promise; } +/** `pollCondition` options whose reads run in a `ReadWindow` over the deadline. */ +export interface PollReadsOptions extends Omit { + readonly reads: ReadWindow; + /** Evaluates the positive condition once, every read run through `reads`. */ + evaluate(reads: ReadWindow): Promise; +} + /** * Polls a condition until it holds (or, when negated, until its negation has * held continuously for the negation grace window), throwing the caller's @@ -120,15 +156,25 @@ export interface PollConditionOptions { * a slow read counts toward the window. A budget shorter than the window * still has to be satisfiable: the negation then only needs to hold for the * whole budget, and passes at the deadline on what it has seen, since a read - * past the deadline has no budget left. A read the deadline cut off (see - * `cutOffAtDeadline`) after an earlier one completed saw nothing: the poll - * ends there. A negation then passes if it has held long enough by the - * time the read is cut off: the read left less than one poll tick unseen, no - * more than the gap between any two reads, so a short budget still passes at - * its deadline on what it saw. + * past the deadline has no budget left. A read the deadline cut off (an + * `OPERATION_TIMEOUT` on a read that started with under one poll tick left) + * after an earlier one completed saw nothing: the poll ends there. A negation + * then passes if it has held long enough by the time the read is cut off: the + * read left less than one poll tick unseen, no more than the gap between any + * two reads, so a short budget still passes at its deadline on what it saw. + */ +export function pollCondition(options: PollConditionOptions): Promise { + return pollReads({ ...options, reads: new ReadWindow(options.deadline) }); +} + +/** + * `pollCondition` with its reads run through `options.reads`: a window with a + * cap lets the last read run past the deadline by the longest read the poll + * has finished, and a read cut off (see `ReadWindow.cutOff`) is one that + * started with under one poll tick, or that longest read, left. */ -export async function pollCondition(options: PollConditionOptions): Promise { - const { deadline, negated } = options; +export async function pollReads(options: PollReadsOptions): Promise { + const { deadline, negated, reads } = options; const startedAt = Date.now(); const grace = Math.min(NEGATION_GRACE_MS, deadline.remaining(startedAt)); let readAt = startedAt; @@ -139,10 +185,10 @@ export async function pollCondition(options: PollConditionOptions): Promise { let retried: unknown; for (;;) { - const startedWithMs = deadline.remaining(); + const startedWithMs = reads.deadline.remaining(); try { - return await this.session.locate(expression, this.operationWithin(deadline)); + return await reads.read((timeoutMs) => this.session.locate(expression, this.readOperation(timeoutMs))); } catch (cause) { // A retry the deadline cut off saw nothing new: the wait ends on the failure it was retrying. - if (retried !== undefined && cutOffAtDeadline(cause, startedWithMs)) throw translateLocatorError(retried, expression); + if (retried !== undefined && reads.cutOff(cause, startedWithMs)) throw translateLocatorError(retried, expression); const engineError = asEngineError(cause); if (engineError?.retryable === true) { if (missingFrame === 'empty' && engineError.code === 'FRAME_NOT_FOUND') return []; - if (!deadline.expired()) { + if (!reads.deadline.expired()) { retried = cause; await sleep(POLL_INTERVAL_MS, this.signal); continue; @@ -216,11 +226,12 @@ export class LocatorEngine { * multiple matches fail immediately with LOCATOR_AMBIGUOUS. */ async resolveExactlyOne(expression: LocatorExpression, deadline: Deadline): Promise { - return (await this.resolveCounted(expression, deadline)).ref; + return (await this.resolveCounted(expression, this.reads(deadline))).ref; } /** `resolveExactlyOne`, timing how long it polled before the match appeared. */ - private async resolveCounted(expression: LocatorExpression, deadline: Deadline): Promise { + private async resolveCounted(expression: LocatorExpression, reads: ReadWindow): Promise { + const { deadline } = reads; const startedMs = Date.now(); // The wait as it happened: a deadline capped by the test's remaining // budget waited less than the action timeout, and the report says so. @@ -234,10 +245,10 @@ export class LocatorEngine { const startedWithMs = deadline.remaining(); let refs: readonly NodeRef[]; try { - refs = await this.resolveOnce(expression, deadline); + refs = await this.resolveOnce(expression, reads); } catch (cause) { // A resolve the deadline cut off, after one that matched nothing, is the wait running out. - if (sampled && cutOffAtDeadline(cause, startedWithMs)) throw notFound(cause); + if (sampled && reads.cutOff(cause, startedWithMs)) throw notFound(cause); throw cause; } sampled = true; @@ -255,8 +266,11 @@ export class LocatorEngine { * every resolve does: that repairs a race with a navigation, it does not * wait for a match. */ - async resolveNow(expression: LocatorExpression, deadline: Deadline = this.deadline(this.options.actionTimeout)): Promise { - return this.resolveOnce(expression, deadline, 'empty'); + async resolveNow( + expression: LocatorExpression, + reads: ReadWindow = new ReadWindow(this.deadline(this.options.actionTimeout)), + ): Promise { + return this.resolveOnce(expression, reads, 'empty'); } /** @@ -267,14 +281,14 @@ export class LocatorEngine { * re-resolves while the deadline remains instead of failing the test. */ async read(expression: LocatorExpression): Promise { - const deadline = this.deadline(this.options.actionTimeout); + const reads = this.reads(this.deadline(this.options.actionTimeout)); for (;;) { - const ref = await this.resolveExactlyOne(expression, deadline); + const { ref } = await this.resolveCounted(expression, reads); try { - return await this.session.read(ref, this.operationWithin(deadline)); + return await reads.read((timeoutMs) => this.session.read(ref, this.readOperation(timeoutMs))); } catch (cause) { const engineError = asEngineError(cause); - if (engineError?.code === 'NODE_STALE' && engineError.retryable && !deadline.expired()) { + if (engineError?.code === 'NODE_STALE' && engineError.retryable && !reads.deadline.expired()) { continue; } throw translateLocatorError(cause, expression); @@ -289,15 +303,18 @@ export class LocatorEngine { * member says nothing about the others; a stale set at the deadline is * `LOCATOR_NOT_FOUND`. */ - async readAllNow(expression: LocatorExpression, deadline: Deadline = this.deadline(this.options.actionTimeout)): Promise { + async readAllNow( + expression: LocatorExpression, + reads: ReadWindow = new ReadWindow(this.deadline(this.options.actionTimeout)), + ): Promise { for (;;) { - const refs = await this.resolveOnce(expression, deadline, 'empty'); + const refs = await this.resolveOnce(expression, reads, 'empty'); try { const nodes: SemanticNode[] = []; - for (const ref of refs) nodes.push(await this.session.read(ref, this.operationWithin(deadline))); + for (const ref of refs) nodes.push(await reads.read((timeoutMs) => this.session.read(ref, this.readOperation(timeoutMs)))); return nodes; } catch (cause) { - if (asEngineError(cause)?.code === 'NODE_STALE' && !deadline.expired()) { + if (asEngineError(cause)?.code === 'NODE_STALE' && !reads.deadline.expired()) { await sleep(POLL_INTERVAL_MS, this.signal); continue; } @@ -314,10 +331,10 @@ export class LocatorEngine { */ async tryRead( expression: LocatorExpression, - deadline: Deadline, + reads: ReadWindow, missingFrame: MissingFrame = 'wait', ): Promise<{ node: SemanticNode | null; count: number }> { - return this.readOne(expression, deadline, missingFrame); + return this.readOne(expression, reads, missingFrame); } /** @@ -326,19 +343,19 @@ export class LocatorEngine { * matches are `LOCATOR_AMBIGUOUS`. */ async readNow(expression: LocatorExpression): Promise { - const { node } = await this.readOne(expression, this.deadline(this.options.actionTimeout), 'empty'); + const { node } = await this.readOne(expression, new ReadWindow(this.deadline(this.options.actionTimeout)), 'empty'); return node; } private async readOne( expression: LocatorExpression, - deadline: Deadline, + reads: ReadWindow, missingFrame: MissingFrame, ): Promise<{ node: SemanticNode | null; count: number }> { - const ref = assertSingle(await this.resolveOnce(expression, deadline, missingFrame), expression); + const ref = assertSingle(await this.resolveOnce(expression, reads, missingFrame), expression); if (ref === null) return { node: null, count: 0 }; try { - const node = await this.session.read(ref, this.operationWithin(deadline)); + const node = await reads.read((timeoutMs) => this.session.read(ref, this.readOperation(timeoutMs))); return { node, count: 1 }; } catch (cause) { if (asEngineError(cause)?.code === 'NODE_STALE') { @@ -420,14 +437,15 @@ export class LocatorEngine { details: locatorDetails(expression, Date.now() - startedMs), ...(cause === undefined ? {} : { cause }), }); + const reads = this.reads(deadline); let sampled = false; for (;;) { const startedWithMs = deadline.remaining(); let node: SemanticNode | null; try { - ({ node } = await this.tryRead(expression, deadline)); + ({ node } = await this.tryRead(expression, reads)); } catch (cause) { - if (sampled && cutOffAtDeadline(cause, startedWithMs)) throw notVisible(cause); + if (sampled && reads.cutOff(cause, startedWithMs)) throw notVisible(cause); throw cause; } sampled = true; @@ -526,7 +544,7 @@ export class LocatorEngine { const startedMs = Date.now(); let stale = 0; for (;;) { - const { ref, waitedMs } = await this.resolveCounted(expression, deadline); + const { ref, waitedMs } = await this.resolveCounted(expression, this.reads(deadline)); // Read now, from the resolve's own cache: a dragTo's target resolve // below supersedes this ref, and the node it named would be gone. const node = this.options.recordEvent === undefined ? undefined : await this.session.read(ref, this.operationWithin(deadline)).catch(() => undefined); diff --git a/packages/e2e/src/locator/screen.ts b/packages/e2e/src/locator/screen.ts index 571a388682..f664d4ce22 100644 --- a/packages/e2e/src/locator/screen.ts +++ b/packages/e2e/src/locator/screen.ts @@ -43,7 +43,7 @@ import { testIdQuery, textQuery, } from './expression.ts'; -import { cutOffAtDeadline, type Deadline, isOperationTimeout, POLL_INTERVAL_MS, pollCondition } from '../internal/time.ts'; +import { type Deadline, isOperationTimeout, POLL_INTERVAL_MS, pollReads } from '../internal/time.ts'; import { SampleHistory } from '../expect/samples.ts'; import type { ScreenshotContext } from '../run/screenshots.ts'; @@ -275,14 +275,15 @@ class ScreenImpl implements Screen { details: locatorDetails(internals.expression, Date.now() - startedMs), ...(cause === undefined ? {} : { cause }), }); + const reads = engine.reads(deadline); let sampled = false; for (;;) { const startedWithMs = deadline.remaining(); let node: SemanticNode | null; try { - ({ node } = await engine.tryRead(internals.expression, deadline)); + ({ node } = await engine.tryRead(internals.expression, reads)); } catch (cause) { - if (sampled && cutOffAtDeadline(cause, startedWithMs)) throw notVisible(cause); + if (sampled && reads.cutOff(cause, startedWithMs)) throw notVisible(cause); throw cause; } sampled = true; @@ -627,12 +628,13 @@ class LocatorImpl extends ScreenImpl implements Locator { const startedMs = Date.now(); const samples = new SampleHistory('waitFor', (text) => engine.redact(text)); await samples.record(engine, () => - pollCondition({ + pollReads({ deadline, + reads: engine.reads(deadline), signal: engine.signal, negated: false, - evaluate: async () => { - const { node } = await engine.tryRead(this.expression, deadline, ABSENCE_STATES.has(state) ? 'empty' : 'wait'); + evaluate: async (reads) => { + const { node } = await engine.tryRead(this.expression, reads, ABSENCE_STATES.has(state) ? 'empty' : 'wait'); samples.add(node === null ? 'absent' : isNodeVisible(node) ? 'visible' : 'hidden'); return inWaitForState(node, state); }, diff --git a/packages/e2e/tests/helpers/screen-over.ts b/packages/e2e/tests/helpers/screen-over.ts index 7df5bc5e31..96ed2f1c96 100644 --- a/packages/e2e/tests/helpers/screen-over.ts +++ b/packages/e2e/tests/helpers/screen-over.ts @@ -28,8 +28,8 @@ import { StepRecorder } from '../../src/run/steps.ts'; import type { Screen } from '../../src/types.ts'; export interface ScreenOverOptions { - /** Answers every `locate`. */ - readonly locate: (expression: LocatorExpression) => readonly SemanticNode[] | Promise; + /** Answers every `locate`, with the operation it runs under. */ + readonly locate: (expression: LocatorExpression, operation: OperationContext) => readonly SemanticNode[] | Promise; /** Answers every `observe`; the root's ref is what a viewport swipe is addressed to. */ readonly observe: () => EngineSnapshot; /** Receives every node action with the operation it runs under; without it the engine declares no actions. */ @@ -52,7 +52,7 @@ export function screenOver(options: ScreenOverOptions): { screen: Screen; steps: version: '1', spiVersion: 1, observe: async () => options.observe(), - locate: async (expression) => options.locate(expression), + locate: async (expression, operation) => options.locate(expression, operation), ...(perform === undefined ? {} : { diff --git a/packages/e2e/tests/unit/locator-engine.test.ts b/packages/e2e/tests/unit/locator-engine.test.ts index 3f0f537bff..39b9afbd7b 100644 --- a/packages/e2e/tests/unit/locator-engine.test.ts +++ b/packages/e2e/tests/unit/locator-engine.test.ts @@ -15,7 +15,7 @@ import { } from '../../src/engine/surface.ts'; import { LocatorEngine, isNodeVisible, translateLocatorError } from '../../src/locator/engine.ts'; import { E2EError } from '../../src/internal/errors.ts'; -import { Deadline } from '../../src/internal/time.ts'; +import { Deadline, sleep, withTimeout } from '../../src/internal/time.ts'; import { AttemptBudget } from '../../src/run/budget.ts'; import { defineEngine, LOCATOR_ACTION_KINDS } from '../../src/engine/index.ts'; import { createEngineSession } from '../../src/engine/session.ts'; @@ -32,6 +32,14 @@ const EXPRESSION: LocatorExpression = { query: { kind: 'role', value: { kind: 'string', value: 'button', exact: true } }, }; +/** A resolve that answers `refs` after `ms`. */ +function slowResolve(ms: number, refs: readonly NodeRef[]): () => Promise { + return async () => { + await sleep(ms); + return refs; + }; +} + interface ScreenScript { resolve?: Array<(() => readonly NodeRef[]) | 'stale' | 'frame' | 'failure' | 'foreign-stale'>; read?: Array<(() => SemanticNode | Promise) | 'stale' | 'stale-retryable' | 'failure' | 'foreign-stale'>; @@ -51,6 +59,11 @@ function foreignStale(retryable: boolean): Error { return error; } +/** Runs one fake engine call on its operation's budget, as an engine must: past it, the call is `OPERATION_TIMEOUT`. */ +function withinBudget(operation: OperationContext, call: () => T | Promise): Promise { + return withTimeout(Promise.resolve().then(call), operation.timeoutMs, () => new EngineError('OPERATION_TIMEOUT', 'operation timed out', { retryable: false })); +} + function makeEngine(script: ScreenScript, options: { actionTimeout?: number; budget?: AttemptBudget } = {}) { const calls = { resolve: 0, read: 0, perform: 0 }; const origins: (string | undefined)[] = []; @@ -65,16 +78,16 @@ function makeEngine(script: ScreenScript, options: { actionTimeout?: number; bud async locate(_expression: LocatorExpression, operation: OperationContext) { resolveTimeouts.push(operation.timeoutMs); const step = next(script.resolve, 'resolve'); - if (step === undefined || typeof step === 'function') return step?.() ?? [REF]; + if (step === undefined || typeof step === 'function') return withinBudget(operation, () => step?.() ?? [REF]); if (step === 'stale') throw new EngineError('NODE_STALE', 'stale', { retryable: true }); if (step === 'foreign-stale') throw foreignStale(true); if (step === 'frame') throw new EngineError('FRAME_NOT_FOUND', 'frame missing', { retryable: true }); throw new EngineError('ENGINE_FAILURE', 'engine died', { retryable: false }); }, - async read() { + async read(_ref: NodeRef, operation: OperationContext) { const step = next(script.read, 'read'); - if (step === undefined || typeof step === 'function') return step?.() ?? NODE; + if (step === undefined || typeof step === 'function') return withinBudget(operation, () => step?.() ?? NODE); if (step === 'stale') throw new EngineError('NODE_STALE', 'stale', { retryable: false }); if (step === 'foreign-stale') throw foreignStale(false); if (step === 'stale-retryable') throw new EngineError('NODE_STALE', 'stale', { retryable: true }); @@ -158,7 +171,7 @@ describe('LocatorEngine resolve retry contract', () => { it('translates a non-retryable resolve failure immediately without retrying', async () => { const { engine, calls } = makeEngine({ resolve: ['failure'] }); - await expect(engine.resolveNow(EXPRESSION, engine.deadline())).rejects.toMatchObject({ + await expect(engine.resolveNow(EXPRESSION, engine.reads(engine.deadline()))).rejects.toMatchObject({ category: 'infrastructure', code: 'ENGINE_FAILURE', }); @@ -170,7 +183,7 @@ describe('LocatorEngine resolve retry contract', () => { { resolve: Array.from({ length: 50 }, () => 'stale' as const) }, { actionTimeout: 350 }, ); - await expect(engine.resolveNow(EXPRESSION, engine.deadline())).rejects.toMatchObject({ + await expect(engine.resolveNow(EXPRESSION, engine.reads(engine.deadline()))).rejects.toMatchObject({ category: 'test', code: 'LOCATOR_NOT_FOUND', }); @@ -202,17 +215,44 @@ describe('LocatorEngine resolve retry contract', () => { }); it('keeps a resolve that hung with budget to spare a timeout, never a missing node', async () => { - const deadline = new Deadline(600); - let calls = 0; - const { engine } = makeEngine({ - resolve: Array.from({ length: 50 }, () => async () => { - calls += 1; - if (calls === 1) return [] as readonly NodeRef[]; - await new Promise((resolve) => setTimeout(resolve, deadline.remaining())); - throw new EngineError('OPERATION_TIMEOUT', 'locate timed out', { retryable: false }); - }) as unknown as Array<() => readonly NodeRef[]>, + const deadline = new Deadline(2_000); + const { engine, calls } = makeEngine({ + resolve: [ + async () => { + await sleep(100); + return []; + }, + () => new Promise(() => undefined), + ] as unknown as Array<() => readonly NodeRef[]>, }); await expect(engine.resolveExactlyOne(EXPRESSION, deadline)).rejects.toMatchObject({ code: 'ACTION_FAILED' }); + expect(calls.resolve).toBe(2); + }); + + it('lets a slow last resolve finish past the deadline: a late match resolves', async () => { + const deadline = new Deadline(450); + const { engine, resolveTimeouts } = makeEngine({ + resolve: [slowResolve(200, []), slowResolve(200, [REF])] as unknown as Array<() => readonly NodeRef[]>, + }); + await expect(engine.resolveExactlyOne(EXPRESSION, deadline)).resolves.toBe(REF); + expect(resolveTimeouts).toEqual([450, 350]); + }); + + it('ends a wait whose slow last resolve found nothing as LOCATOR_NOT_FOUND, not a timeout', async () => { + const deadline = new Deadline(450); + const { engine, calls } = makeEngine({ + resolve: [slowResolve(200, []), slowResolve(200, [])] as unknown as Array<() => readonly NodeRef[]>, + }); + const failure = await engine.resolveExactlyOne(EXPRESSION, deadline).catch((error: unknown) => error); + expect(failure).toMatchObject({ code: 'LOCATOR_NOT_FOUND' }); + expect((failure as Error).cause).toBeUndefined(); + expect(calls.resolve).toBe(2); + }); + + it('gives each retry of a resolve what is left of its budget, not the whole budget again', async () => { + const { engine, resolveTimeouts } = makeEngine({ resolve: ['stale', 'stale', () => [REF]] }, { actionTimeout: 1_000 }); + await engine.resolveNow(EXPRESSION, engine.reads(engine.deadline())); + expect(resolveTimeouts).toEqual([1_000, 900, 800]); }); it('ends a frame wait the deadline cut off on the missing frame, as LOCATOR_NOT_FOUND', async () => { @@ -320,13 +360,13 @@ describe('AttemptBudget.capped', () => { describe('LocatorEngine read contract', () => { it('collapses stale reads to a zero-count sample so assertion polls re-resolve', async () => { const { engine } = makeEngine({ read: ['stale'] }); - const sample = await engine.tryRead(EXPRESSION, new Deadline(5_000)); + const sample = await engine.tryRead(EXPRESSION, engine.reads(new Deadline(5_000))); expect(sample).toEqual({ node: null, count: 0 }); }); it('translates non-stale read failures', async () => { const { engine } = makeEngine({ read: ['failure'] }); - await expect(engine.tryRead(EXPRESSION, new Deadline(5_000))).rejects.toMatchObject({ + await expect(engine.tryRead(EXPRESSION, engine.reads(new Deadline(5_000)))).rejects.toMatchObject({ code: 'ENGINE_FAILURE', category: 'infrastructure', }); @@ -347,13 +387,13 @@ describe('LocatorEngine readAllNow contract', () => { resolve: [() => [REF, OTHER_REF]], read: [() => NODE, () => OTHER_NODE], }); - expect(await engine.readAllNow(EXPRESSION, engine.deadline())).toEqual([NODE, OTHER_NODE]); + expect(await engine.readAllNow(EXPRESSION, engine.reads(engine.deadline()))).toEqual([NODE, OTHER_NODE]); expect(calls).toMatchObject({ resolve: 1, read: 2 }); }); it('answers zero matches with an empty list without waiting', async () => { const { engine, calls } = makeEngine({ resolve: [() => []] }); - expect(await engine.readAllNow(EXPRESSION, engine.deadline())).toEqual([]); + expect(await engine.readAllNow(EXPRESSION, engine.reads(engine.deadline()))).toEqual([]); expect(calls).toMatchObject({ resolve: 1, read: 0 }); }); @@ -362,20 +402,20 @@ describe('LocatorEngine readAllNow contract', () => { resolve: [() => [REF, OTHER_REF], () => [OTHER_REF]], read: ['stale', () => OTHER_NODE], }); - expect(await engine.readAllNow(EXPRESSION, engine.deadline())).toEqual([OTHER_NODE]); + expect(await engine.readAllNow(EXPRESSION, engine.reads(engine.deadline()))).toEqual([OTHER_NODE]); expect(calls).toMatchObject({ resolve: 2, read: 2 }); }); it('gives up on a set that stays stale at the deadline as LOCATOR_NOT_FOUND', async () => { const { engine } = makeEngine({ read: ['stale', 'stale', 'stale', 'stale', 'stale'] }); - await expect(engine.readAllNow(EXPRESSION, new Deadline(150))).rejects.toMatchObject({ + await expect(engine.readAllNow(EXPRESSION, engine.reads(new Deadline(150)))).rejects.toMatchObject({ code: 'LOCATOR_NOT_FOUND', }); }); it('translates non-stale read failures', async () => { const { engine } = makeEngine({ read: ['failure'] }); - await expect(engine.readAllNow(EXPRESSION, engine.deadline())).rejects.toMatchObject({ code: 'ENGINE_FAILURE' }); + await expect(engine.readAllNow(EXPRESSION, engine.reads(engine.deadline()))).rejects.toMatchObject({ code: 'ENGINE_FAILURE' }); }); }); @@ -539,7 +579,7 @@ describe('LocatorEngine visible queries', () => { const { engine } = makeLocatorEngineOverEngine(); const ref = await engine.resolveExactlyOne(build(true), new Deadline(5_000)); expect(ref.id).toBe('shown'); - expect(await engine.resolveNow(build(true), engine.deadline())).toHaveLength(1); + expect(await engine.resolveNow(build(true), engine.reads(engine.deadline()))).toHaveLength(1); }); it.each(kinds)('%s without visible keeps the hidden twin, so the pair is LOCATOR_AMBIGUOUS', async (_kind, build) => { @@ -550,7 +590,7 @@ describe('LocatorEngine visible queries', () => { await expect(engine.resolveExactlyOne(build(false), new Deadline(5_000))).rejects.toMatchObject({ code: 'LOCATOR_AMBIGUOUS', }); - expect(await engine.resolveNow(build(undefined), engine.deadline())).toHaveLength(2); + expect(await engine.resolveNow(build(undefined), engine.reads(engine.deadline()))).toHaveLength(2); }); it('names the predicate in the ambiguity message when two visible nodes remain', async () => { @@ -575,7 +615,7 @@ describe('LocatorEngine visible queries', () => { const indexed: LocatorExpression = { kind: 'index', source: kinds[1]![1](true), index: 'first' }; // The adapter cannot know which of the engine's answers came first, so it // must not second-guess them; the engine applied `visible` before `first`. - expect(await engine.resolveNow(indexed, engine.deadline())).toHaveLength(2); + expect(await engine.resolveNow(indexed, engine.reads(engine.deadline()))).toHaveLength(2); expect(expressions[0]).toEqual(indexed); }); }); @@ -598,7 +638,7 @@ describe('LocatorEngine retries a cross-realm driver failure', () => { it('treats a foreign stale read as zero matches while polling', async () => { const { engine } = makeEngine({ read: ['foreign-stale'] }); - await expect(engine.tryRead(EXPRESSION, new Deadline(0))).resolves.toEqual({ + await expect(engine.tryRead(EXPRESSION, engine.reads(new Deadline(0)))).resolves.toEqual({ node: null, count: 0, }); diff --git a/packages/e2e/tests/unit/locator-wait-for.test.ts b/packages/e2e/tests/unit/locator-wait-for.test.ts index ce9eb6b63b..b75f33fd51 100644 --- a/packages/e2e/tests/unit/locator-wait-for.test.ts +++ b/packages/e2e/tests/unit/locator-wait-for.test.ts @@ -6,7 +6,9 @@ */ import { afterEach, describe, expect, it } from 'vitest'; -import { resolveExpression, type SemanticNode } from '../../src/engine/index.ts'; +import { EngineError, resolveExpression, type SemanticNode } from '../../src/engine/index.ts'; +import { expect as expectFixture } from '../../src/expect/index.ts'; +import { sleep, withTimeout } from '../../src/internal/time.ts'; import type { Locator } from '../../src/types.ts'; import { invalid } from '../helpers/invalid.ts'; import { screenOver } from '../helpers/screen-over.ts'; @@ -117,3 +119,30 @@ describe('locator.waitFor validation', () => { expect(steps.all()).toEqual([]); }); }); + +describe('a slow last read', () => { + /** A screen whose every read takes 300 ms, bounded by its operation's budget, and whose banner shows up at 1050 ms. */ + function slowScreen() { + let nodes: readonly SemanticNode[] = []; + timers.push(setTimeout(() => (nodes = [banner]), 1_050)); + const { screen } = screenOver({ + locate: (expression, operation) => + withTimeout( + sleep(300).then(() => resolveExpression(expression, nodes)), + operation.timeoutMs, + () => new EngineError('OPERATION_TIMEOUT', 'locate timed out', { retryable: false }), + ), + observe: () => snapshot(nodes), + timeoutMs: 1_000, + }); + return screen.getByTestId('banner'); + } + + it('still finishes past the deadline, so waitFor sees a node that showed up during it', async () => { + await expect(slowScreen().waitFor()).resolves.toBeUndefined(); + }); + + it('still finishes past the deadline, so an assertion sees a node that showed up during it', async () => { + await expect(expectFixture(slowScreen()).toBeVisible()).resolves.toBeUndefined(); + }); +}); diff --git a/packages/e2e/tests/unit/time.test.ts b/packages/e2e/tests/unit/time.test.ts index c3e89644c9..ec2ef89189 100644 --- a/packages/e2e/tests/unit/time.test.ts +++ b/packages/e2e/tests/unit/time.test.ts @@ -6,6 +6,8 @@ import { NEGATION_GRACE_MS, POLL_INTERVAL_MS, pollCondition, + pollReads, + ReadWindow, sleep, withTimeout, } from '../../src/internal/time.ts'; @@ -358,6 +360,61 @@ describe('pollCondition', () => { await expect(early).rejects.toBe(cut); }); + it('lets the last read run past the deadline by the longest read the poll finished, up to the window cap', async () => { + vi.useFakeTimers(); + const deadline = new Deadline(350); + const timeouts: number[] = []; + let calls = 0; + const promise = pollReads({ + deadline, + reads: new ReadWindow(deadline, new Deadline(400)), + signal: new AbortController().signal, + negated: false, + evaluate: (reads) => + reads.read(async (timeoutMs) => { + timeouts.push(timeoutMs); + calls += 1; + const readDuration = calls === 1 ? 200 : 50; + await withTimeout(sleep(readDuration), timeoutMs, () => new EngineError('OPERATION_TIMEOUT', 'locate timed out', { retryable: false })); + return calls === 2; + }), + onTimeout: () => new Error('poll timed out'), + }); + await vi.advanceTimersByTimeAsync(1_000); + await expect(promise).resolves.toBeUndefined(); + expect(timeouts).toEqual([350, 100]); + }); + + it('ends on a read cut off within the longest read time of the deadline, and fails on one that hung with more left', async () => { + vi.useFakeTimers(); + const cut = new EngineError('OPERATION_TIMEOUT', 'locate timed out', { retryable: false }); + const poll = (timeoutMs: number) => { + const deadline = new Deadline(timeoutMs); + let calls = 0; + return pollReads({ + deadline, + reads: new ReadWindow(deadline), + signal: new AbortController().signal, + negated: false, + evaluate: (reads) => + reads.read(async () => { + calls += 1; + await sleep(300); + if (calls === 1) return false; + throw cut; + }), + onTimeout: () => new Error('poll timed out'), + }); + }; + // The second read starts with 200 ms left: under the 300 ms the first took, so the deadline cut it. + const within = expect(poll(600)).rejects.toThrow('poll timed out'); + // With 600 ms left, more than any read took, the read hung. + const hung = expect(poll(1_000)).rejects.toBe(cut); + await vi.advanceTimersByTimeAsync(2_000); + await within; + await hung; + }); + it('keeps a read that hung most of the wait a failure, and never lets a negation pass on it', async () => { vi.useFakeTimers(); const cut = new EngineError('OPERATION_TIMEOUT', 'locate timed out', { retryable: false }); diff --git a/packages/mobile/package.json b/packages/mobile/package.json index dacdf21367..c9b672df9e 100644 --- a/packages/mobile/package.json +++ b/packages/mobile/package.json @@ -65,7 +65,7 @@ }, "peerDependencies": { "ai": "^7.0.0", - "e2e": ">=0.15.0 <1" + "e2e": ">=0.21.4 <1" }, "peerDependenciesMeta": { "ai": { diff --git a/packages/mobile/src/engine.ts b/packages/mobile/src/engine.ts index 3757306c38..ac4e675737 100644 --- a/packages/mobile/src/engine.ts +++ b/packages/mobile/src/engine.ts @@ -31,10 +31,10 @@ export function buildEngine(surface: AgentDeviceSurface): EngineHandle { startAttempt: (context) => surface.startAttempt(context), endAttempt: (context) => surface.endAttempt(context), dispose: (context) => surface.dispose(context), - observe: (operation, options) => surface.observe(operation, options), - locate: (expression, operation) => surface.locate(expression, operation), // The harness signal does not abort at an operation's budget, so each - // input enforces its own; see InputBudget in support.ts. + // operation enforces its own; see InputBudget in support.ts. + observe: (operation, options) => surface.observe(operation, options, surface.inputBudget('observe', operation.timeoutMs)), + locate: (expression, operation) => surface.locate(expression, operation, surface.inputBudget('locate', operation.timeoutMs)), perform: (ref, action, operation) => surface.perform(ref, action, operation, surface.inputBudget(action.kind, operation.timeoutMs)), actions: DEVICE_ACTIONS, performAt: (point, action, operation) => surface.performAt(point, action, operation, surface.inputBudget(action.kind, operation.timeoutMs)), @@ -54,7 +54,7 @@ export function buildEngine(surface: AgentDeviceSurface): EngineHandle { reset: (operation) => surface.reset(operation), }, artifacts: { - screenshot: (label, operation) => surface.screenshot(label, operation), + screenshot: (label, operation) => surface.screenshot(label, operation, surface.inputBudget('screenshot', operation.timeoutMs)), startVideo: (operation) => surface.startVideo(operation), stopVideo: (operation) => surface.stopVideo(operation), }, diff --git a/packages/mobile/src/support.ts b/packages/mobile/src/support.ts index 8b75f86edf..19f75da9c6 100644 --- a/packages/mobile/src/support.ts +++ b/packages/mobile/src/support.ts @@ -26,10 +26,9 @@ export function cancelled(text: string): EngineError { const MIN_ANSWER_MS = 250; /** - * One input operation's budget (`actionTimeout`, or the call's `timeout`), - * which the harness signal does not enforce. Only the device commands that - * send input run under it; reads stay unbounded, so a locator poll keeps its - * last snapshot and a target settling before a tap is relocated in full. + * One operation's budget (its `timeoutMs`), which the harness signal does not + * enforce. Every device command the operation sends runs under it: the + * inputs through `send`, the snapshots and screenshots through `read`. */ export class InputBudget { private readonly endsAt: number; @@ -57,12 +56,8 @@ export class InputBudget { * landed, so it is `ACTION_MAY_HAVE_COMMITTED` and the runner never repeats it. */ send(dispatch: () => Promise, holdMs = 0): Promise { - const remaining = this.endsAt - Date.now(); - if (remaining <= 0) { - return Promise.reject( - this.sent ? this.maybeCommitted() : new EngineError('OPERATION_TIMEOUT', `${this.label} timed out before it was sent`, { retryable: false }), - ); - } + const remaining = this.remainingMs(); + if (remaining <= 0) return Promise.reject(this.spent()); if (holdMs >= remaining) { return Promise.reject( new EngineError( @@ -77,6 +72,34 @@ export class InputBudget { return withTimeout(pending, Math.max(remaining, MIN_ANSWER_MS), () => this.maybeCommitted()); } + /** + * Runs one device read with what is left of the budget. With none left it + * reads nothing. A read that does not answer in time is `OPERATION_TIMEOUT`, + * or `ACTION_MAY_HAVE_COMMITTED` once an input of this operation went out, + * so the runner never repeats that input. + */ + read(dispatch: () => Promise): Promise { + const remaining = this.remainingMs(); + if (remaining <= 0) return Promise.reject(this.spent()); + return withTimeout(this.track(dispatch()), remaining, () => + this.sent + ? this.maybeCommitted() + : new EngineError('OPERATION_TIMEOUT', `${this.label} timed out before the device answered`, { retryable: false }), + ); + } + + /** Milliseconds left of the budget; zero or less once it is spent. */ + remainingMs(): number { + return this.endsAt - Date.now(); + } + + /** The failure of a command the spent budget did not send. */ + private spent(): EngineError { + return this.sent + ? this.maybeCommitted() + : new EngineError('OPERATION_TIMEOUT', `${this.label} timed out before it was sent`, { retryable: false }); + } + private maybeCommitted(): EngineError { return new EngineError('ACTION_MAY_HAVE_COMMITTED', `${this.label} timed out before the device answered; its input may have been dispatched`, { retryable: false, diff --git a/packages/mobile/src/surface.ts b/packages/mobile/src/surface.ts index 1263f02df5..0e76e96f46 100644 --- a/packages/mobile/src/surface.ts +++ b/packages/mobile/src/surface.ts @@ -300,6 +300,11 @@ function sendInput(input: InputBudget | undefined, dispatch: () => Promise return input === undefined ? dispatch() : input.send(dispatch); } +/** Runs a device read under its operation's budget, or directly from a call that has none. */ +function readWithin(budget: InputBudget | undefined, dispatch: () => Promise): Promise { + return budget === undefined ? dispatch() : budget.read(dispatch); +} + function sleep(ms: number, signal: AbortSignal): Promise { return new Promise((resolve) => { const timer = setTimeout(done, ms); @@ -515,7 +520,7 @@ export class AgentDeviceSurface { return result; } - /** The budget one input runs under; its device commands stay in flight until they settle. */ + /** The budget one operation runs under; its device commands stay in flight until they settle. */ inputBudget(label: string, timeoutMs: number): InputBudget { return new InputBudget(label, timeoutMs, (pending) => this.track(pending)); } @@ -935,12 +940,19 @@ export class AgentDeviceSurface { return installed; } - private async snapshot(signal: AbortSignal, interactiveOnly: boolean): Promise { + private async snapshot(signal: AbortSignal, interactiveOnly: boolean, budget?: InputBudget): Promise { let last: RawSnapshot = {}; + let captureMs = 0; for (const backoffMs of SPARSE_RETRY_BACKOFF_MS) { - if (backoffMs > 0) await sleep(backoffMs, signal); + if (backoffMs > 0) { + // A sparse capture is still the screen: a retry the budget cannot fit returns it instead of timing out. + if (budget !== undefined && budget.remainingMs() <= backoffMs + captureMs) return last; + await sleep(backoffMs, signal); + } if (signal.aborted) throw new EngineError('CANCELLED', 'snapshot cancelled', { retryable: false }); - last = await this.capture(signal, interactiveOnly); + const startedAt = Date.now(); + last = await this.capture(signal, interactiveOnly, budget); + captureMs = Date.now() - startedAt; this.launching = false; if (last.appBundleId !== undefined || last.appName !== undefined) { this.appIdentity = last.appBundleId ?? last.appName; @@ -954,11 +966,12 @@ export class AgentDeviceSurface { * One capture, taken again once when the iOS runner acquired the tree but * failed its own presentation check on it (a viewport it could not read, a * malformed graph). The check is per capture and a capture is a read, so - * the retry is safe; a second failure is the runner's and propagates. + * the retry is safe; a second failure is the runner's and propagates. Each + * capture runs under `budget`, so one the budget abandoned is not retried. */ - private async capture(signal: AbortSignal, interactiveOnly: boolean): Promise { + private async capture(signal: AbortSignal, interactiveOnly: boolean, budget?: InputBudget): Promise { const take = (): Promise => - this.command('snapshot', (client) => client.capture.snapshot({ interactiveOnly }), signal); + readWithin(budget, () => this.command('snapshot', (client) => client.capture.snapshot({ interactiveOnly }), signal)); try { return await take(); } catch (cause) { @@ -972,9 +985,9 @@ export class AgentDeviceSurface { * anything is open is an empty screen rather than a fault: the model's next * move is the open tool, and failing the step would take that move away. */ - private async snapshotOrEmpty(operation: OperationContext, interactiveOnly: boolean): Promise { + private async snapshotOrEmpty(operation: OperationContext, interactiveOnly: boolean, budget?: InputBudget): Promise { try { - return await this.snapshot(operation.signal, interactiveOnly); + return await this.snapshot(operation.signal, interactiveOnly, budget); } catch (cause) { if (!this.managesApp && cause instanceof EngineError && cause.code === 'INVALID_STATE') return { nodes: [] }; throw cause; @@ -985,16 +998,18 @@ export class AgentDeviceSurface { * Snapshot for a locate; undefined for a screen agent-device could not read * yet (an app still on its splash, or one iOS does not report running yet * after a launch). The harness polls a locate until its deadline, so that - * screen matches nothing and the poll waits for it to render. A capture that leaves no budget for another poll fails with the - * reason instead, so a wait that ends on an unreadable screen says so. + * screen matches nothing and the poll waits for it to render. A capture + * that leaves less of the budget than it took fails with the reason + * instead, so a wait that ends on an unreadable screen says so. */ - private async locateSnapshot(operation: OperationContext): Promise { + private async locateSnapshot(operation: OperationContext, budget?: InputBudget): Promise { const startedMs = Date.now(); try { - return await this.snapshotOrEmpty(operation, false); + return await this.snapshotOrEmpty(operation, false, budget); } catch (cause) { + const tookMs = Date.now() - startedMs; const arriving = isUnreadableCapture(cause) || (this.launching && isAppNotRunning(cause)); - if (operation.signal.aborted || !arriving || Date.now() - startedMs >= operation.timeoutMs) throw cause; + if (operation.signal.aborted || !arriving || tookMs >= operation.timeoutMs - tookMs) throw cause; return undefined; } } @@ -1037,19 +1052,19 @@ export class AgentDeviceSurface { * measures every rect and point against the viewport, so an invented one * would misplace every tap. */ - private async viewportFor(projected: ProjectedSnapshot, signal: AbortSignal): Promise { + private async viewportFor(projected: ProjectedSnapshot, signal: AbortSignal, budget?: InputBudget): Promise { const read = projected.viewport; const known = this.knownViewport; if (known !== undefined) { if (read === undefined) return known; if (!sameScreen(read, known)) { - const probed = await this.probeViewport(signal); + const probed = await this.probeViewport(signal, budget); if (probed !== undefined && !sameScreen(read, probed)) return known; } this.knownViewport = read; return read; } - const probed = await this.probeViewport(signal); + const probed = await this.probeViewport(signal, budget); if (probed === undefined) { throw new EngineError( 'ENGINE_FAILURE', @@ -1062,18 +1077,18 @@ export class AgentDeviceSurface { } /** The device's logical screen size as its screenshot reports it; undefined when it reports none. */ - private async probeViewport(signal: AbortSignal): Promise { - const result = await this.captureScreenshot(signal, async (shot) => shot); + private async probeViewport(signal: AbortSignal, budget?: InputBudget): Promise { + const result = await this.captureScreenshot(signal, async (shot) => shot, {}, budget); return logicalScreenSize(result); } - async observe(operation: OperationContext, options?: EngineObserveOptions): Promise { - const raw = await this.snapshotOrEmpty(operation, this.options.snapshot === 'interactive'); + async observe(operation: OperationContext, options?: EngineObserveOptions, budget?: InputBudget): Promise { + const raw = await this.snapshotOrEmpty(operation, this.options.snapshot === 'interactive', budget); const projected = this.project(raw); this.generation = new Map(projected.index.map((entry) => [entry.id, this.bind(entry, projected)])); - const viewport = await this.viewportFor(projected, operation.signal); + const viewport = await this.viewportFor(projected, operation.signal, budget); const location = screenLocation(raw.appBundleId ?? raw.appName ?? this.appIdentity, screenTitle(projected)); - const capture = options?.pixels === true ? await this.capturePixels(operation, projected, viewport, { normalizeStatusBar: options.comparable === true }) : undefined; + const capture = options?.pixels === true ? await this.capturePixels(operation, projected, viewport, { normalizeStatusBar: options.comparable === true }, budget) : undefined; const keyboardVisible = measuredKeyboard(raw); return { root: screenRoot(projected.roots, viewport), @@ -1086,8 +1101,8 @@ export class AgentDeviceSurface { } /** Retains only action bindings for matches, independently of the observation generation. */ - async locate(expression: LocatorExpression, operation: OperationContext): Promise { - const raw = await this.locateSnapshot(operation); + async locate(expression: LocatorExpression, operation: OperationContext, budget?: InputBudget): Promise { + const raw = await this.locateSnapshot(operation, budget); if (raw === undefined) return []; const projected = this.project(raw); this.traceScreen(raw, projected); @@ -1216,14 +1231,14 @@ export class AgentDeviceSurface { } /** Refreshes a control after a transition wait, keeping the binding when no wait was needed. */ - private async settled(entry: NodeBinding, operation: OperationContext): Promise { - if (await this.waitForTransition(entry, operation)) return this.relocated(entry, operation); + private async settled(entry: NodeBinding, operation: OperationContext, budget?: InputBudget): Promise { + if (await this.waitForTransition(entry, operation)) return this.relocated(entry, operation, budget); return entry; } /** The same control in a fresh snapshot; input mutations refuse a missing target or changed security facts. */ - private async relocated(entry: NodeBinding, operation: OperationContext, input = false): Promise { - const raw = await this.snapshotOrEmpty(operation, false); + private async relocated(entry: NodeBinding, operation: OperationContext, budget?: InputBudget, input = false): Promise { + const raw = await this.snapshotOrEmpty(operation, false, budget); const projected = this.project(raw); const found = this.refind(entry, projected.index); if (input && (isTruncated(raw) || found === undefined || @@ -1285,9 +1300,9 @@ export class AgentDeviceSurface { let target = entry; if (filling) { if (deterministic) await this.waitForTransition(entry, operation); - target = await this.relocated(entry, operation, true); + target = await this.relocated(entry, operation, input, true); } else if (deterministic) { - target = await this.settled(entry, operation); + target = await this.settled(entry, operation, input); } switch (action.kind) { case 'tap': @@ -1484,11 +1499,11 @@ export class AgentDeviceSurface { * keyboard. */ private async dismissKeyboardByGesture(signal: AbortSignal, input: InputBudget | undefined): Promise { - let raw = await this.dismissKeyboardTip(await this.snapshot(signal, false), signal, input); + let raw = await this.dismissKeyboardTip(await this.snapshot(signal, false, input), signal, input); if (!keyboardShowing(raw)) return; for (const axis of ['horizontal', 'vertical'] as const) { const projected = projectSnapshot(raw.nodes ?? [], { mintId: () => 'keyboard', viewport: raw.viewport }); - const viewport = await this.viewportFor(projected, signal); + const viewport = await this.viewportFor(projected, signal, input); const from = keyboardDragStart(projected, viewport, keyboardTop(raw, viewport)); if (from === undefined) { throw new EngineError( @@ -1501,7 +1516,7 @@ export class AgentDeviceSurface { ? { x: from.x - viewport.width * KEYBOARD_DRAG_RATIO, y: from.y } : { x: from.x, y: from.y - viewport.height * KEYBOARD_DRAG_RATIO }; await this.command('keyboard.dismiss', (client) => sendInput(input, () => client.interactions.swipe({ from, to })), signal); - raw = await this.snapshot(signal, false); + raw = await this.snapshot(signal, false, input); if (!keyboardShowing(raw)) return; } throw new EngineError( @@ -1525,7 +1540,7 @@ export class AgentDeviceSurface { const button = nodes.find((node) => node.label === 'Continue' && node.rect !== undefined && node.rect.y > tipTop); if (button?.rect === undefined) return raw; await this.command('keyboard.dismiss', (client) => sendInput(input, () => client.interactions.press(centreOf(button.rect!))), signal); - return await this.snapshot(signal, false); + return await this.snapshot(signal, false, input); } async back(operation: OperationContext, input: InputBudget): Promise { @@ -1587,10 +1602,10 @@ export class AgentDeviceSurface { * bounds cannot be masked, and an image that cannot be redacted is not * written at all. */ - async screenshot(label: string | undefined, operation: OperationContext): Promise { + async screenshot(label: string | undefined, operation: OperationContext, budget?: InputBudget): Promise { const attempt = this.attempt; if (attempt === undefined) throw invalidState('screenshot outside an attempt'); - const masked = await this.maskedScreenshot(operation.signal); + const masked = await this.maskedScreenshot(operation.signal, budget); attempt.screenshots += 1; const name = `${String(attempt.screenshots).padStart(3, '0')}-${sanitizeFilename(label ?? 'screenshot')}.png`; const relative = path.join('screenshots', name); @@ -1600,8 +1615,8 @@ export class AgentDeviceSurface { } /** Raw device pixels; cleanup follows the capture even when its caller abandons it. */ - private rawScreenshot(signal?: AbortSignal, capture: ScreenshotCapture = {}): Promise { - return this.captureScreenshot(signal, async (shot, file) => new Uint8Array(readFileSync(shot.path ?? file)), capture); + private rawScreenshot(signal?: AbortSignal, capture: ScreenshotCapture = {}, budget?: InputBudget): Promise { + return this.captureScreenshot(signal, async (shot, file) => new Uint8Array(readFileSync(shot.path ?? file)), capture, budget); } /** @@ -1613,16 +1628,19 @@ export class AgentDeviceSurface { signal: AbortSignal | undefined, read: (shot: RawScreenshotResult, file: string) => Promise, capture: ScreenshotCapture = {}, + budget?: InputBudget, ): Promise { - return this.command('screenshot', async (client) => { - const directory = mkdtempSync(path.join(tmpdir(), 'e2e-agent-device-')); - const file = path.join(directory, 'screenshot.png'); - try { - return await read(await client.capture.screenshot({ path: file, ...(capture.normalizeStatusBar === true ? { normalizeStatusBar: true } : {}) }), file); - } finally { - rmSync(directory, { recursive: true, force: true }); - } - }, signal); + return readWithin(budget, () => + this.command('screenshot', async (client) => { + const directory = mkdtempSync(path.join(tmpdir(), 'e2e-agent-device-')); + const file = path.join(directory, 'screenshot.png'); + try { + return await read(await client.capture.screenshot({ path: file, ...(capture.normalizeStatusBar === true ? { normalizeStatusBar: true } : {}) }), file); + } finally { + rmSync(directory, { recursive: true, force: true }); + } + }, signal), + ); } /** @@ -1631,7 +1649,7 @@ export class AgentDeviceSurface { * throws when a secure field cannot be covered, because an image that may * hold a credential must not leave the engine. */ - private async maskedScreenshot(signal?: AbortSignal): Promise<{ data: Uint8Array; masked: number }> { + private async maskedScreenshot(signal?: AbortSignal, budget?: InputBudget): Promise<{ data: Uint8Array; masked: number }> { const operation: OperationContext = { signal: signal ?? new AbortController().signal, timeoutMs: 30_000, @@ -1639,8 +1657,8 @@ export class AgentDeviceSurface { attemptId: '', origin: 'test', }; - const projected = this.project(await this.snapshotOrEmpty(operation, false)); - const data = await this.rawScreenshot(signal); + const projected = this.project(await this.snapshotOrEmpty(operation, false, budget)); + const data = await this.rawScreenshot(signal, {}, budget); const masked = redactSecure(data, projected, this.knownViewport); if (masked === undefined) { throw new EngineError('ENGINE_FAILURE', 'a secure field on screen could not be masked; screenshot withheld', { @@ -1652,18 +1670,21 @@ export class AgentDeviceSurface { /** * Viewport pixels for an observation. Best-effort: a screenshot that cannot - * be produced or redacted costs the observation its image, not the step. + * be produced or redacted costs the observation its image, not the step, + * unless the operation's budget ran out. */ private async capturePixels( operation: OperationContext, projected: ProjectedSnapshot, viewport: ViewportSize, capture: ScreenshotCapture, + budget?: InputBudget, ): Promise<{ pixels: ObservationPixels; masked: number } | undefined> { let raw: Uint8Array; try { - raw = await this.rawScreenshot(operation.signal, capture); - } catch { + raw = await this.rawScreenshot(operation.signal, capture, budget); + } catch (cause) { + if (cause instanceof EngineError && cause.code === 'OPERATION_TIMEOUT') throw cause; return undefined; } const redacted = redactSecure(raw, projected, viewport); diff --git a/packages/mobile/tests/unit/engine.test.ts b/packages/mobile/tests/unit/engine.test.ts index 0a0e4b7033..dcd8d439a3 100644 --- a/packages/mobile/tests/unit/engine.test.ts +++ b/packages/mobile/tests/unit/engine.test.ts @@ -975,15 +975,154 @@ describe('observation', () => { expect(settled).toBe(true); }); - it('lets a locate outlive its budget: a poll keeps its last read, so a slow screen reads as missing, not as a timeout', async () => { + it('bounds a snapshot by the operation budget', async () => { const h = harness(); await openAttempt(h); vi.useFakeTimers(); try { - h.fake.respond('capture.snapshot', () => new Promise((resolve) => setTimeout(() => resolve(SETTINGS_SNAPSHOT), 3_000))); + h.fake.respond('capture.snapshot', () => new Promise((resolve) => setTimeout(() => resolve(SETTINGS_SNAPSHOT), 5_000))); const read = h.engine.locate!({ kind: 'query', query: { kind: 'text', value: { kind: 'string', value: 'About', exact: true } } }, { ...operation(), timeoutMs: 1_000 }); + const assertion = expect(read).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT' }); + await vi.advanceTimersByTimeAsync(1_000); + await assertion; + } finally { + vi.useRealTimers(); + } + }); + + it('returns a sparse capture when the budget cannot fit a retry, instead of timing out', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + let snapshots = 0; + h.fake.respond('capture.snapshot', () => { + snapshots += 1; + return Promise.resolve({ nodes: [], snapshotQuality: { state: 'sparse' } }); + }); + const read = h.engine.locate!( + { kind: 'query', query: { kind: 'text', value: { kind: 'string', value: 'About', exact: true } } }, + { ...operation(), timeoutMs: 500 }, + ); + const assertion = expect(read).resolves.toEqual([]); + await vi.advanceTimersByTimeAsync(1_500); + await assertion; + expect(snapshots).toBe(1); + } finally { + vi.useRealTimers(); + } + }); + + it('bounds screenshot by operation budget', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + h.fake.respond('capture.screenshot', () => new Promise((resolve) => setTimeout(() => resolve({ path: '' }), 5_000))); + const shot = h.engine.artifacts!.screenshot('hung shot', { ...operation(), timeoutMs: 1_000 }); + const assertion = expect(shot).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT' }); + await vi.advanceTimersByTimeAsync(1_000); + await assertion; + } finally { + vi.useRealTimers(); + } + }); + + it('rethrows OPERATION_TIMEOUT from capturePixels during observe', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + h.fake.respond('capture.screenshot', () => new Promise((resolve) => setTimeout(() => resolve({ path: '' }), 5_000))); + const obs = h.engine.observe!({ ...operation(), timeoutMs: 1_000 }, { pixels: true }); + const assertion = expect(obs).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT' }); + await vi.advanceTimersByTimeAsync(1_000); + await assertion; + } finally { + vi.useRealTimers(); + } + }); + + it('shares one budget across observe steps so screenshot cannot take a fresh budget', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + // The snapshot carries its geometry, so the only screenshot is the observation's pixels. + h.fake.respond('capture.snapshot', () => new Promise((resolve) => setTimeout(() => resolve({ ...SETTINGS_SNAPSHOT, viewport: { width: 390, height: 844 } }), 1_500))); + let screenshots = 0; + h.fake.respond('capture.screenshot', () => { + screenshots += 1; + return new Promise(() => undefined); + }); + const started = Date.now(); + const obs = h.engine.observe!({ ...operation(), timeoutMs: 2_000 }, { pixels: true }); + const assertion = expect(obs).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT' }); + await vi.advanceTimersByTimeAsync(2_000); + await assertion; + expect(screenshots).toBe(1); + expect(Date.now() - started).toBe(2_000); + } finally { + vi.useRealTimers(); + } + }); + + it('bounds the snapshots of a keyboard dismissal by its budget, and reports one cut off after the drag as possibly committed', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + h.fake.respond('command.keyboard', () => { + throw new AppError('UNSUPPORTED_OPERATION', 'Unable to dismiss the iOS keyboard: the keyboard exposes no dismiss key'); + }); + const keyboardUp = { ...SETTINGS_SNAPSHOT, viewport: { width: 390, height: 844 }, keyboard: { kind: 'visible', frame: { x: 0, y: 583, width: 390, height: 261 } } }; + let snapshots = 0; + h.fake.respond('capture.snapshot', () => (snapshots++ === 0 ? keyboardUp : new Promise(() => undefined))); + const dismiss = h.engine.keyboard!.dismiss!({ ...operation(), timeoutMs: 1_000 }); + const assertion = expect(dismiss).rejects.toMatchObject({ code: 'ACTION_MAY_HAVE_COMMITTED' }); + await vi.advanceTimersByTimeAsync(1_000); + await assertion; + expect(h.fake.calls.filter((call) => call.method === 'interactions.swipe')).toHaveLength(1); + } finally { + vi.useRealTimers(); + } + }); + + it('finishes a slow read the budget covers: a poll grants its last read the time reads take', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + h.fake.respond('capture.snapshot', () => new Promise((resolve) => setTimeout(() => resolve(SETTINGS_SNAPSHOT), 3_000))); + const about = { kind: 'query', query: { kind: 'text', value: { kind: 'string', value: 'About', exact: true } } } as const; + // The last read of a poll that has 500 ms left, after reads that took 3 s. + const read = h.engine.locate!(about, { ...operation(), timeoutMs: 3_500 }); + const assertion = expect(read).resolves.toHaveLength(1); + await vi.advanceTimersByTimeAsync(3_000); + await assertion; + } finally { + vi.useRealTimers(); + } + }); + + it('takes no second snapshot for a capture the budget abandoned', async () => { + const h = harness(); + await openAttempt(h); + vi.useFakeTimers(); + try { + let snapshots = 0; + const presentationFailure = () => + new AppError('COMMAND_FAILED', 'regular iOS snapshot presentation requires a valid viewport', { reason: 'invalid-viewport' }); + h.fake.respond('capture.snapshot', () => { + snapshots += 1; + return new Promise((_, reject) => setTimeout(() => reject(presentationFailure()), 1_500)); + }); + const about = { kind: 'query', query: { kind: 'text', value: { kind: 'string', value: 'About', exact: true } } } as const; + const read = h.engine.locate!(about, { ...operation(), timeoutMs: 1_000 }); + const assertion = expect(read).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT' }); await vi.advanceTimersByTimeAsync(3_000); - await expect(read).resolves.toHaveLength(1); + await assertion; + expect(snapshots).toBe(1); } finally { vi.useRealTimers(); } @@ -1065,10 +1204,10 @@ describe('a screen agent-device cannot read yet', () => { await openAttempt(h); vi.useFakeTimers(); try { - h.fake.respond('capture.snapshot', () => new Promise((_, reject) => setTimeout(() => reject(insufficientContent()), 3_000))); + h.fake.respond('capture.snapshot', () => new Promise((_, reject) => setTimeout(() => reject(insufficientContent()), 600))); const located = h.engine.locate!(ABOUT, { ...operation(), timeoutMs: 1_000 }); const settled = expect(located).rejects.toMatchObject({ code: 'ENGINE_FAILURE', message: expect.stringContaining('insufficient foreground app content') }); - await vi.advanceTimersByTimeAsync(3_000); + await vi.advanceTimersByTimeAsync(600); await settled; } finally { vi.useRealTimers(); diff --git a/packages/mobile/tests/unit/support.test.ts b/packages/mobile/tests/unit/support.test.ts index 1dbc32679a..683ad42794 100644 --- a/packages/mobile/tests/unit/support.test.ts +++ b/packages/mobile/tests/unit/support.test.ts @@ -42,6 +42,35 @@ describe('support helpers', () => { message: expect.stringMatching(/^longPress holds for 3000 ms, but only 2000 ms of its timeout are left/), }); expect(held).toBe(false); + + } finally { + vi.useRealTimers(); + } + }); + + it('runs a read with what is left of its budget, and reports one cut off after an input as possibly committed', async () => { + const hung = () => new Promise(() => undefined); + vi.useFakeTimers(); + try { + await expect(new InputBudget('snapshot', 300, (pending) => pending).read(async () => 'tree')).resolves.toBe('tree'); + + const cut = new InputBudget('snapshot', 200, (pending) => pending).read(hung); + const timedOut = expect(cut).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT', message: 'snapshot timed out before the device answered' }); + await vi.advanceTimersByTimeAsync(200); + await timedOut; + + const spent = new InputBudget('snapshot', 100, (pending) => pending); + await vi.advanceTimersByTimeAsync(100); + await expect(spent.read(async () => 'late')).rejects.toMatchObject({ code: 'OPERATION_TIMEOUT', message: 'snapshot timed out before it was sent' }); + + // After a swipe went out, a read that does not answer must not let a replay send the swipe again. + const dismissal = new InputBudget('keyboard dismiss', 300, (pending) => pending); + await dismissal.send(async () => undefined); + const after = dismissal.read(hung); + const committed = expect(after).rejects.toMatchObject({ code: 'ACTION_MAY_HAVE_COMMITTED' }); + await vi.advanceTimersByTimeAsync(300); + await committed; + await expect(dismissal.read(async () => 'late')).rejects.toMatchObject({ code: 'ACTION_MAY_HAVE_COMMITTED' }); } finally { vi.useRealTimers(); }