Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
5d093a1
fix(mobile): bound reads by operation budget with engine readLatency …
Totopo27 Oct 13, 2026
1d99afb
fix(mobile): bound screenshot reads, interrupt sparse retries on time…
Totopo27 Oct 13, 2026
41cd4a6
fix(mobile): rethrow screenshot timeouts in capturePixels and align r…
Totopo27 Oct 14, 2026
da823fe
docs(mobile): note that screenshot timeouts propagate from capturePixels
Totopo27 Oct 14, 2026
edd367a
fix(mobile): measure read latency dynamically and fold read budget in…
Totopo27 Oct 14, 2026
b8fdf72
Merge remote-tracking branch 'origin/main' into fix/1099-mobile-reads…
okwasniewski Oct 16, 2026
7c9aed8
fix(mobile): give the last read of a wait the time reads take
okwasniewski Oct 16, 2026
21aeaa9
fix(engine): keep ReadWindow off the public poll options
okwasniewski Oct 16, 2026
aaac086
Merge branch 'upstream/main' into fix/1099-mobile-reads-budget
Totopo27 Oct 16, 2026
2018295
fix(mobile): check signal on sparse snapshot budget exhaustion and ex…
Totopo27 Oct 16, 2026
e62ea7c
fix(mobile): require e2e 0.21.3, revert extra abort check, tighten re…
okwasniewski Oct 16, 2026
b13b9ec
Merge branch 'main' into fix/1099-mobile-reads-budget
Totopo27 Oct 22, 2026
02ad4dd
Merge branch 'main' into fix/1099-mobile-reads-budget
Totopo27 Oct 23, 2026
f7f9584
fix(mobile): require e2e 0.21.4, restore locateSnapshot JSDoc
okwasniewski Oct 25, 2026
f9edf91
Merge branch 'main' of https://github.com/tester-army/e2e into fix/10…
Totopo27 Oct 25, 2026
39e3e99
test(locator): restore readAllNow call-count assertion lost in merge
okwasniewski Oct 26, 2026
f4e8c8e
Merge remote-tracking branch 'origin/main' into rfhr-1112
okwasniewski Oct 28, 2026
7f1d05e
refactor(locator): take a ReadWindow in resolveNow and readAllNow
okwasniewski Oct 28, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/last-read-grace.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions .changeset/mobile-reads-budget.md
Original file line number Diff line number Diff line change
@@ -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.
9 changes: 7 additions & 2 deletions docs/mobile.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

<CodeGroup>
```bash npm
Expand Down
11 changes: 8 additions & 3 deletions docs/reference/engine.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -1409,8 +1413,9 @@ export const RETRYABLE_ENGINE_ERROR_CODES: ReadonlySet<EngineErrorCode> = 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 |
Expand Down
6 changes: 5 additions & 1 deletion packages/e2e/src/engine/contract.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
17 changes: 9 additions & 8 deletions packages/e2e/src/expect/async.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -221,18 +222,18 @@ class AsyncExpectationImpl implements AsyncExpectation {
return spec.evaluableNode?.(sample.node) ?? true;
}

private async sample(spec: MatcherSpec, deadline: Deadline): Promise<Sample> {
private async sample(spec: MatcherSpec, reads: ReadWindow): Promise<Sample> {
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: [] };
}

Expand Down
20 changes: 10 additions & 10 deletions packages/e2e/src/expect/screenshot-capture.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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<Capture> {
export function screenshotCapturer(context: ScreenContext, request: CaptureRequest, reads: ReadWindow): () => Promise<Capture> {
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<Capture> {
async function captureOnce(context: ScreenContext, request: CaptureRequest, reads: ReadWindow, state: { scrolled: boolean }): Promise<Capture> {
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`);
Expand All @@ -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 });
}
}
Expand Down
14 changes: 9 additions & 5 deletions packages/e2e/src/expect/screenshot.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -32,6 +32,7 @@ interface Run {
readonly api: string;
readonly call: ScreenshotCall;
readonly stored: Stored;
readonly reads: ReadWindow;
readonly capture: () => Promise<Capture>;
}

Expand Down Expand Up @@ -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');
Expand Down Expand Up @@ -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 () => {
Expand Down Expand Up @@ -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 () => {
Expand Down
82 changes: 64 additions & 18 deletions packages/e2e/src/internal/time.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<T>(call: (timeoutMs: number) => Promise<T>): Promise<T> {
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. */
Expand All @@ -110,6 +139,13 @@ export interface PollConditionOptions {
onTimeout(cause?: unknown): Error | Promise<Error>;
}

/** `pollCondition` options whose reads run in a `ReadWindow` over the deadline. */
export interface PollReadsOptions extends Omit<PollConditionOptions, 'evaluate'> {
readonly reads: ReadWindow;
/** Evaluates the positive condition once, every read run through `reads`. */
evaluate(reads: ReadWindow): Promise<boolean | undefined>;
}

/**
* Polls a condition until it holds (or, when negated, until its negation has
* held continuously for the negation grace window), throwing the caller's
Expand All @@ -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<void> {
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<void> {
const { deadline, negated } = options;
export async function pollReads(options: PollReadsOptions): Promise<void> {
const { deadline, negated, reads } = options;
const startedAt = Date.now();
const grace = Math.min(NEGATION_GRACE_MS, deadline.remaining(startedAt));
let readAt = startedAt;
Expand All @@ -139,10 +185,10 @@ export async function pollCondition(options: PollConditionOptions): Promise<void
const startedWithMs = deadline.remaining(readAt);
let value: boolean | undefined;
try {
value = await options.evaluate();
value = await options.evaluate(reads);
sampled = true;
} catch (cause) {
if (!sampled || !cutOffAtDeadline(cause, startedWithMs)) throw cause;
if (!sampled || !reads.cutOff(cause, startedWithMs)) throw cause;
if (negated && holds(Math.min(Date.now(), deadline.endsAt))) return;
throw await options.onTimeout(cause);
}
Expand Down
Loading
Loading