Skip to content

Commit f6afa01

Browse files
committed
test(ios): recover the E2E visibility search from a scroll that overshoots its target
A controlled iOS scroll can still release with inertia when the host is loaded: the app misses the slow tail of the eased drag and UIKit flings with a mid-drag velocity (~420 pt/s measured), so one scroll down 0.75 moved content 719-852 pt instead of 439-505 pt and carried the one-row automation-longpress target past the viewport. The forward-only search then had nowhere to go (#2491). The search now follows three forward scrolls (2.25 viewports, unchanged) with three shorter reverse scrolls, whose travel plus a measured fling stays inside one viewport, and gives a surface the read reports as unsettled a bounded pause before re-reading it instead of re-reading at once.
1 parent 9fac266 commit f6afa01

2 files changed

Lines changed: 152 additions & 92 deletions

File tree

‎test/integration/ios-simulator-e2e-visibility-scroll.test.ts‎

Lines changed: 95 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@ import assert from 'node:assert/strict';
22
import test from 'node:test';
33

44
import type { CliJsonResult } from './cli-json.ts';
5-
import { searchForVisibleElement } from './ios-simulator-e2e/live-assertions.ts';
5+
import {
6+
searchForVisibleElement,
7+
type ScrollSearchDevice,
8+
} from './ios-simulator-e2e/live-assertions.ts';
69

710
function result(status: number, details?: Record<string, unknown>): CliJsonResult {
811
return {
@@ -13,84 +16,114 @@ function result(status: number, details?: Record<string, unknown>): CliJsonResul
1316
};
1417
}
1518

16-
test('an existing offscreen element scrolls until the visibility probe passes', async () => {
17-
const probes = [result(1), result(0)];
18-
const probeAttempts: number[] = [];
19-
const scrollAttempts: number[] = [];
20-
21-
await searchForVisibleElement(
22-
'id="automation-longpress"',
23-
async (attempt) => {
24-
probeAttempts.push(attempt);
25-
return probes.shift() ?? result(1);
19+
const UNSETTLED = { unsettledGesture: { action: 'scroll', positionals: [] } };
20+
21+
/**
22+
* A vertical list the search drives. Offsets are in viewports; the target is visible while the
23+
* offset lies inside `visible`. Each scroll moves by the next planned travel, clamped to the list
24+
* bounds. `movesUntilSettled` keeps the surface moving after every scroll that moved until the
25+
* search pauses to settle it, so each read before that misses with `unsettledGesture`: the CI
26+
* failure shape.
27+
*/
28+
function list(options: {
29+
visible?: readonly [number, number];
30+
downTravel?: readonly number[];
31+
end?: number;
32+
movesUntilSettled?: boolean;
33+
}) {
34+
const downTravel = [...(options.downTravel ?? [])];
35+
const end = options.end ?? 10;
36+
let offset = 0;
37+
let moving = false;
38+
const log: string[] = [];
39+
const device: ScrollSearchDevice = {
40+
probeVisibility: async (probe) => {
41+
log.push(`probe ${probe}`);
42+
const [from, to] = options.visible ?? [Infinity, Infinity];
43+
if (!moving && offset >= from && offset <= to) return result(0);
44+
return result(1, moving ? UNSETTLED : { reason: 'selector_not_found' });
2645
},
27-
async (attempt) => {
28-
scrollAttempts.push(attempt);
46+
settle: async () => {
47+
log.push('settle');
48+
moving = false;
2949
},
30-
);
50+
scroll: async (step) => {
51+
const travel = step.direction === 'down' ? (downTravel.shift() ?? 0.75) : -0.5;
52+
const next = Math.min(end, Math.max(0, offset + travel));
53+
const moved = next !== offset;
54+
offset = next;
55+
moving = options.movesUntilSettled === true && moved;
56+
log.push(`scroll ${step.direction} ${step.amount}`);
57+
},
58+
};
59+
return { device, log };
60+
}
3161

32-
assert.deepEqual(probeAttempts, [1, 2]);
33-
assert.deepEqual(scrollAttempts, [1]);
62+
test('an existing offscreen element scrolls until the visibility probe passes', async () => {
63+
const { device, log } = list({ visible: [0.5, 1.2] });
64+
65+
await searchForVisibleElement('id="target"', device);
66+
67+
assert.deepEqual(log, ['probe 1', 'scroll down 0.75', 'probe 2']);
3468
});
3569

3670
test('a stalled capture retries without scrolling or consuming an attempt', async () => {
3771
const probes = [result(1, { captureStalled: true }), result(0)];
38-
const probeAttempts: number[] = [];
39-
const scrollAttempts: number[] = [];
40-
41-
await searchForVisibleElement(
42-
'id="automation-longpress"',
43-
async (attempt) => {
44-
probeAttempts.push(attempt);
45-
return probes.shift() ?? result(1);
46-
},
47-
async (attempt) => {
48-
scrollAttempts.push(attempt);
72+
const scrolls: string[] = [];
73+
74+
await searchForVisibleElement('id="target"', {
75+
probeVisibility: async () => probes.shift() ?? result(1),
76+
settle: async () => assert.fail('a stalled capture is not a moving surface'),
77+
scroll: async (step) => {
78+
scrolls.push(step.direction);
4979
},
50-
);
80+
});
5181

52-
assert.deepEqual(probeAttempts, [1, 1]);
53-
assert.deepEqual(scrollAttempts, []);
82+
assert.deepEqual([probes.length, scrolls], [0, []]);
5483
});
5584

56-
/**
57-
* The CI failure shape: the element is on screen only at offset 1, and the first read after each
58-
* scroll lands on a surface still moving, so it misses with `unsettledGesture`.
59-
*/
60-
function listWithUnsettledFirstReads(visibleAt?: number) {
61-
let offset = 0;
62-
let moving = false;
63-
const probes: number[] = [];
64-
const scrolls: number[] = [];
65-
const probe = async (attempt: number) => {
66-
probes.push(attempt);
67-
const unsettled = moving;
68-
moving = false;
69-
if (!unsettled && offset === visibleAt) return result(0);
70-
return result(1, unsettled ? { unsettledGesture: { action: 'scroll', positionals: [] } } : {});
71-
};
72-
const scroll = async (attempt: number) => {
73-
scrolls.push(attempt);
74-
offset += 1;
75-
moving = true;
76-
};
77-
return { probes, scrolls, probe, scroll };
78-
}
85+
test('an unsettled miss waits for the surface to settle and re-reads at the same offset', async () => {
86+
const { device, log } = list({ visible: [0.5, 1.2], movesUntilSettled: true });
7987

80-
test('an unsettled miss after the scroll that reached the element is re-read at the same offset', async () => {
81-
const list = listWithUnsettledFirstReads(1);
88+
await searchForVisibleElement('id="target"', device);
89+
90+
assert.deepEqual(log, ['probe 1', 'scroll down 0.75', 'probe 2', 'settle', 'probe 3']);
91+
});
8292

83-
await searchForVisibleElement('id="target"', list.probe, list.scroll);
93+
test('a forward scroll that overshoots the element is recovered by scrolling back', async () => {
94+
// Measured on an iOS 26 simulator under host load: one `scroll down 0.75` moved content 852 pt
95+
// instead of its usual 439-505 pt, which carried a one-row target past the viewport.
96+
const { device, log } = list({
97+
visible: [0.6, 1.25],
98+
downTravel: [1.4, 0.75, 0.75],
99+
end: 2.2,
100+
movesUntilSettled: true,
101+
});
84102

85-
assert.deepEqual([list.probes, list.scrolls], [[1, 2, 2], [1]]);
103+
await searchForVisibleElement('id="target"', device);
104+
105+
assert.deepEqual(
106+
log.filter((entry) => entry.startsWith('scroll')),
107+
['scroll down 0.75', 'scroll down 0.75', 'scroll down 0.75', 'scroll up 0.5', 'scroll up 0.5'],
108+
);
86109
});
87110

88-
test('a real absence still fails after the forward scrolls, naming every step', async () => {
89-
const list = listWithUnsettledFirstReads();
111+
test('a real absence still fails after both sweeps, naming every step', async () => {
112+
const { device, log } = list({ movesUntilSettled: true });
90113

91114
await assert.rejects(
92-
searchForVisibleElement('id="target"', list.probe, list.scroll),
93-
/scroll after attempt 3: [\s\S]*probe 4:/,
115+
searchForVisibleElement('id="target"', device),
116+
/scroll down 3: [\s\S]*scroll up 6: [\s\S]*probe \d+:/,
117+
);
118+
assert.deepEqual(
119+
log.filter((entry) => entry.startsWith('scroll')),
120+
[
121+
'scroll down 0.75',
122+
'scroll down 0.75',
123+
'scroll down 0.75',
124+
'scroll up 0.5',
125+
'scroll up 0.5',
126+
'scroll up 0.5',
127+
],
94128
);
95-
assert.deepEqual(list.scrolls, [1, 2, 3]);
96129
});

‎test/integration/ios-simulator-e2e/live-assertions.ts‎

Lines changed: 57 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -40,33 +40,53 @@ export function snapshotNodes(result: { json?: any }): LiveSnapshotNode[] {
4040
return nodes as LiveSnapshotNode[];
4141
}
4242

43-
const SCROLL_SEARCH_ATTEMPTS = 4;
43+
/**
44+
* Three forward scrolls reach 2.25 viewports of finger travel. The reverse steps are shorter: a
45+
* controlled iOS scroll can still carry post-release inertia under host load (ADR 0013), so a
46+
* forward step can carry a short target past the viewport, and a reverse step plus that inertia
47+
* must stay inside one viewport so the reverse sweep cannot skip it again.
48+
*/
49+
const FORWARD = { direction: 'down', amount: '0.75' } as const;
50+
const REVERSE = { direction: 'up', amount: '0.5' } as const;
51+
const SCROLL_SEARCH_PLAN = [FORWARD, FORWARD, FORWARD, REVERSE, REVERSE, REVERSE];
4452
// A stalled capture, or one taken while the last scroll was still moving, says nothing about where
4553
// the element is, so re-reading it must not consume a scroll. A couple of re-reads per scroll absorb
4654
// a slow runner without masking a real absence.
4755
const SCROLL_SEARCH_REREADS = 2;
56+
const SETTLE_MS = '1000';
57+
58+
export type ScrollSearchStep = (typeof SCROLL_SEARCH_PLAN)[number];
59+
60+
export type ScrollSearchDevice = {
61+
probeVisibility: (probe: number) => Promise<CliJsonResult>;
62+
/** Gives a surface that was still moving a bounded pause before the next read. */
63+
settle: () => Promise<void>;
64+
scroll: (step: ScrollSearchStep, index: number) => Promise<unknown>;
65+
};
4866

4967
export async function assertElementTextAfterScrolling(
5068
context: LiveContext,
5169
selector: string,
5270
expected: string,
5371
): Promise<void> {
54-
await searchForVisibleElement(
55-
selector,
56-
(attempt) =>
72+
await searchForVisibleElement(selector, {
73+
probeVisibility: (probe) =>
5774
runStep(
5875
context,
59-
`check ${selector} visibility after scroll (attempt ${attempt})`,
76+
`check ${selector} visibility (probe ${probe})`,
6077
['is', 'visible', selector],
6178
{ allowFailure: true },
6279
),
63-
(attempt) =>
64-
runStep(context, `scroll toward ${selector} after attempt ${attempt}`, [
80+
settle: async () => {
81+
await runStep(context, `settle before re-reading ${selector}`, ['wait', SETTLE_MS]);
82+
},
83+
scroll: (step, index) =>
84+
runStep(context, `scroll ${step.direction} toward ${selector} (scroll ${index})`, [
6585
'scroll',
66-
'down',
67-
'0.75',
86+
step.direction,
87+
step.amount,
6888
]).then((result) => result.json?.data),
69-
);
89+
});
7090
await assertElementText(context, selector, expected);
7191
}
7292

@@ -78,34 +98,41 @@ export async function assertElementTextAfterScrolling(
7898
*/
7999
export async function searchForVisibleElement(
80100
selector: string,
81-
probeVisibility: (attempt: number) => Promise<CliJsonResult>,
82-
scrollAfterAttempt: (attempt: number) => Promise<unknown>,
101+
device: ScrollSearchDevice,
83102
): Promise<void> {
84-
let rereadsLeft = SCROLL_SEARCH_REREADS;
85103
const history: string[] = [];
86-
87-
for (let attempt = 1; attempt <= SCROLL_SEARCH_ATTEMPTS;) {
88-
const probe = await probeVisibility(attempt);
89-
history.push(`probe ${attempt}: ${JSON.stringify(probe.json ?? { status: probe.status })}`);
90-
if (probe.status === 0) return;
91-
92-
const details = probe.json?.error?.details;
93-
const readNothing = details?.captureStalled === true || details?.unsettledGesture !== undefined;
94-
if (readNothing && rereadsLeft > 0) {
95-
rereadsLeft -= 1;
96-
continue;
104+
let probes = 0;
105+
const readWindow = async (): Promise<boolean> => {
106+
for (let rereads = 0; ; rereads += 1) {
107+
probes += 1;
108+
const result = await device.probeVisibility(probes);
109+
history.push(`probe ${probes}: ${JSON.stringify(result.json ?? { status: result.status })}`);
110+
if (result.status === 0) return true;
111+
const unread = unreadSurface(result);
112+
if (unread === undefined || rereads === SCROLL_SEARCH_REREADS) return false;
113+
if (unread === 'moving') {
114+
await device.settle();
115+
history.push(`settled for ${SETTLE_MS} ms`);
116+
}
97117
}
118+
};
98119

99-
attempt += 1;
100-
if (attempt <= SCROLL_SEARCH_ATTEMPTS) {
101-
const scrolled = await scrollAfterAttempt(attempt - 1);
102-
history.push(`scroll after attempt ${attempt - 1}: ${JSON.stringify(scrolled ?? null)}`);
103-
rereadsLeft = SCROLL_SEARCH_REREADS;
104-
}
120+
for (const [index, step] of SCROLL_SEARCH_PLAN.entries()) {
121+
if (await readWindow()) return;
122+
const scrolled = await device.scroll(step, index + 1);
123+
history.push(`scroll ${step.direction} ${index + 1}: ${JSON.stringify(scrolled ?? null)}`);
105124
}
125+
if (await readWindow()) return;
106126
assert.fail(`${selector} did not become visible after scrolling\n${history.join('\n')}`);
107127
}
108128

129+
/** Why a missed probe says nothing about where the element is, if it says nothing. */
130+
function unreadSurface(result: CliJsonResult): 'moving' | 'stalled' | undefined {
131+
const details = result.json?.error?.details;
132+
if (details?.unsettledGesture !== undefined) return 'moving';
133+
return details?.captureStalled === true ? 'stalled' : undefined;
134+
}
135+
109136
function requireNode(
110137
result: CliJsonResult,
111138
identifier: string,

0 commit comments

Comments
 (0)