Skip to content

Commit ea51273

Browse files
committed
fix: scope scroll progress evidence
1 parent 17d749d commit ea51273

6 files changed

Lines changed: 39 additions & 35 deletions

File tree

‎packages/capture-kit/src/snapshot/scroll-edge-state.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,6 @@ export function verticalEdgeFor(direction: ScrollDirection): ScrollEdge | undefi
1818
export type ScrollEdgeState = {
1919
canScroll: boolean;
2020
emptySnapshot: boolean;
21-
edgeObserved?: boolean;
2221
scope?: string;
2322
/**
2423
* The frame of the container every other field on this record describes, absent when the tree

‎packages/capture-kit/src/snapshot/scroll-edge-state/selection.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,11 +40,6 @@ export function analyzeScrollEdgeState(
4040
return {
4141
canScroll,
4242
emptySnapshot: false,
43-
edgeObserved:
44-
!canScroll &&
45-
(edge === 'bottom'
46-
? container.hiddenContentBelow === false
47-
: container.hiddenContentAbove === false),
4843
// Every selection path admits only `isUsableRect` containers, so a resolved container always
4944
// has a frame to report and its absence always means no container was resolved.
5045
...(container.rect ? { containerRect: container.rect } : {}),

‎packages/daemon/src/execution/scroll-until.test.ts‎

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -237,28 +237,6 @@ test('an unchanged collection without a scroll marker reports no progress', asyn
237237
);
238238
});
239239

240-
test('an explicit edge stops before a gesture', async () => {
241-
const nodes = tree(200, 'Other');
242-
nodes[1]!.hiddenContentBelow = false;
243-
let scrolls = 0;
244-
await assert.rejects(
245-
() => run({ captures: [capture({ nodes })], onScroll: () => (scrolls += 1) }),
246-
(error: unknown) =>
247-
error instanceof AppError && error.details?.reason === 'scroll_until_edge_reached',
248-
);
249-
assert.equal(scrolls, 0);
250-
});
251-
252-
test('visible hidden content overrides a contradictory explicit edge', async () => {
253-
const nodes = tree(2400);
254-
nodes[1]!.hiddenContentBelow = false;
255-
await assert.rejects(
256-
() => run({ captures: [capture({ nodes })], passLimit: 1 }),
257-
(error: unknown) =>
258-
error instanceof AppError && error.details?.reason === 'scroll_until_pass_limit',
259-
);
260-
});
261-
262240
test('content that moved and then stops reports the end of content', async () => {
263241
const frames = [tree(400, 'Other'), tree(200, 'Other')].map((nodes) => capture({ nodes }));
264242
await assert.rejects(
@@ -284,6 +262,29 @@ test('a non-scrollable screen stops after repeated unchanged observations', asyn
284262
assert.equal(scrolls, 3);
285263
});
286264

265+
test('changes outside a stuck scroll container do not imply scrolling', async () => {
266+
const frame = (label: string) =>
267+
capture({ nodes: [...tree(200, 'Other'), { ...row(3, 100, label), parentIndex: 0 }] });
268+
await assert.rejects(
269+
() => run({ captures: [frame('Clock 1'), frame('Clock 2')] }),
270+
(error: unknown) =>
271+
error instanceof AppError && error.details?.reason === 'scroll_until_no_progress',
272+
);
273+
});
274+
275+
test('changes in a tree without a scroll container do not imply scrolling', async () => {
276+
const frame = (label: string) => {
277+
const nodes = tree(200, label).filter((node) => node.index !== 1);
278+
nodes[1]!.parentIndex = 0;
279+
return capture({ nodes });
280+
};
281+
await assert.rejects(
282+
() => run({ captures: [frame('Clock 1'), frame('Clock 2')] }),
283+
(error: unknown) =>
284+
error instanceof AppError && error.details?.reason === 'scroll_until_no_progress',
285+
);
286+
});
287+
287288
test('a horizontal scroll has no edge signal and is bounded by the budget alone', async () => {
288289
let scrolls = 0;
289290
await assert.rejects(

‎packages/daemon/src/execution/scroll-until.ts‎

Lines changed: 14 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ export async function runScrollUntilVisible<TResult>(params: {
5656
const edge = verticalEdgeFor(direction);
5757
let scrolled = false;
5858
let previousFingerprint: string | undefined;
59+
let previousContainer: string | undefined;
5960
let observedMovement = false;
6061
try {
6162
const { passes, result } = await runScrollPasses({
@@ -66,16 +67,24 @@ export async function runScrollUntilVisible<TResult>(params: {
6667
if (refusal) throw scrollUntilCaptureError(direction, selector, refusal);
6768
return captured.nodes as SnapshotNode[];
6869
},
69-
decide: async (nodes, passes) => {
70+
decide: async (nodes) => {
7071
if (await isSelectorVisible(nodes, selector, platform)) return { stop: true };
7172
// Horizontal scrolling has no edge analyzer and uses only the pass budget.
7273
if (!edge) return { stop: false };
7374
const state = await readScrollEdgeState(nodes, edge);
74-
if (state.edgeObserved) throw scrollUntilEdgeError(direction, selector, passes);
75-
if (state.fingerprint && previousFingerprint && state.fingerprint !== previousFingerprint) {
75+
const container = state.containerRect && JSON.stringify([state.containerRect, state.scope]);
76+
if (container !== previousContainer) observedMovement = false;
77+
if (
78+
container &&
79+
container === previousContainer &&
80+
state.fingerprint &&
81+
previousFingerprint &&
82+
state.fingerprint !== previousFingerprint
83+
) {
7684
observedMovement = true;
7785
}
78-
previousFingerprint = state.fingerprint;
86+
previousContainer = container;
87+
previousFingerprint = container ? state.fingerprint : undefined;
7988
return { stop: false, fingerprint: state.fingerprint };
8089
},
8190
passLimit: params.passLimit ?? DEFAULT_SCROLL_UNTIL_PASSES,
@@ -192,7 +201,7 @@ function scrollUntilEdgeError(
192201
): AppError {
193202
return new AppError(
194203
'COMMAND_FAILED',
195-
`scroll ${direction} reached the end of the scrollable content after ${passes} passes without ${selector} becoming visible`,
204+
`scroll ${direction} reached the end of the scrollable content after ${passes} ${passes === 1 ? 'pass' : 'passes'} without ${selector} becoming visible`,
196205
{
197206
reason: 'scroll_until_edge_reached',
198207
selector,

‎src/commands/schema/cli-help-gestures.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Shapes:
2121
agent-device gesture rotate 35 200 420
2222
agent-device gesture transform 200 420 80 -40 2 35 700
2323
agent-device gesture tap 80 300 200 450 310 600 --count 20 --pause-ms 100
24-
scroll <dir> --until <selector> repeats scroll-and-check passes until that element is on screen, then stops: one request instead of a scroll-then-snapshot loop, and it stops on the target rather than overshooting it. It reports the passes it spent; vertical searches compare repeated captures of descendants in the selected scroll container and stop when those captures show no progress. If no container is found, they compare the visible tree. It is refused on top/bottom, which already stop themselves. The default limit is ${DEFAULT_SCROLL_UNTIL_PASSES} gestures. For a longer list, add --max-passes <n> (1–${SCROLL_UNTIL_MAX_PASSES}); it requires --until. Large pass budgets can hit the 90-second request timeout; inspect the current screen and continue with another search if that happens.
24+
scroll <dir> --until <selector> repeats scroll-and-check passes until that element is on screen, then stops: one request instead of a scroll-then-snapshot loop, and it stops on the target rather than overshooting it. It reports the passes it spent; vertical searches compare repeated captures of descendants in the selected scroll container and fail when those captures show no progress. If no container is found, they compare the visible tree. It is refused on top/bottom, which already stop themselves. The default limit is ${DEFAULT_SCROLL_UNTIL_PASSES} gestures. For a longer list, add --max-passes <n> (1–${SCROLL_UNTIL_MAX_PASSES}); it requires --until. Large pass budgets can hit the 90-second request timeout; inspect the current screen and continue with another search if that happens.
2525
longpress accepts coordinates, @refs, or selectors; prefer @ref/selector, coordinates only as a fallback. Duration and gesture scale/center are positional. gesture pan is one finger by default; add --pointer-count 2 for a parallel two-finger pan. Keep count/pause/pattern on one swipe: --count (cap 200), --pause-ms (cap 10000ms), --pattern ping-pong; the combined swipe/pause schedule is capped at 60000ms.
2626
For repeated iOS smoke checks: press <x> <y> --count <n> --jitter-px <n> for tap series, swipe <x1> <y1> <x2> <y2> --count <n> for drag series. gesture tap touches 2 to 5 distinct points and holds them for --hold-ms (default 50, min 16); --count repeats the same contacts (cap 200) with --pause-ms between, the series must fit 60000ms counting about 500ms per repetition, and a repetition costs about 450ms on a physical iPhone. Use press for one finger.
2727

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -540,7 +540,7 @@ agent-device wait 'id="field-phone" value="00 062 91 77"'
540540
### Scroll
541541
542542
- `scroll <direction> [amount]` takes the finger path as a fraction of the viewport (`0.5` is half), or `--pixels <n>` for a fixed distance. Large distances are clamped. The app's scroll physics decide the final offset, so a scroll does not land on an exact position.
543-
- `scroll <direction> --until <selector>` repeats passes until the selector is on screen. A vertical search stops if repeated captures show no progress in the selected scroll container. If no container is found, it compares the visible tree. It stops after at most 12 gestures by default. For a longer list, use `scroll down --until 'id="row-512"' --max-passes 90` (1–200 gestures). The pass limit does not extend the 90-second request timeout. Large pass budgets can hit that timeout; inspect the current screen and continue with another search if that happens. Add an amount (`scroll down 0.8 --until <selector>`) to widen each pass. Use it in `.ad` scripts too, instead of fixed amounts that depend on screen size; see [Replay and E2E testing](/docs/replay-e2e).
543+
- `scroll <direction> --until <selector>` repeats passes until the selector is on screen. A vertical search fails with `COMMAND_FAILED` and `reason: scroll_until_no_progress` if repeated captures show no progress in the selected scroll container. If content moved before stopping, the reason is `scroll_until_edge_reached`. If no container is found, it compares the visible tree. It stops after at most 12 gestures by default. For a longer list, use `scroll down --until 'id="row-512"' --max-passes 90` (1–200 gestures). The pass limit does not extend the 90-second request timeout. Large pass budgets can hit that timeout; inspect the current screen and continue with another search if that happens. Add an amount (`scroll down 0.8 --until <selector>`) to widen each pass. Use it in `.ad` scripts too, instead of fixed amounts that depend on screen size; see [Replay and E2E testing](/docs/replay-e2e).
544544
- Default snapshot text summarizes off-screen interactive content instead of listing refs. `scroll <direction> --settle` (and `back --settle`) waits for the UI to go quiet and returns the diff with fresh refs, so you don't need another `snapshot -i`. Settle is best-effort and never fails the action.
545545
- On Android, settle ignores an allowlist of system-bar containers and shade/keyguard status headers; other SystemUI overlays remain content. Appium settle also applies package rules for keyboard and system chrome.
546546
- With a keyboard up on iOS or Android, the swipe stays above the keyboard (reported as `keyboardAvoided` and `keyboardMinY`) and the keyboard stays open. If too little room is left, the command refuses with `scroll_keyboard_occludes_surface`; run `keyboard dismiss` first.

0 commit comments

Comments
 (0)