Skip to content

Commit 0214cc4

Browse files
committed
docs(scroll): describe reduced momentum and the Android controlled-scroll limit
The scroll docs only carried the generic app-physics caveat, not the release-behavior contract itself. State plainly that scroll releases with reduced momentum rather than an exact stop, and document Android's controlled-release durationMs ceiling (9840ms, reserved headroom for the braking tail added in #2371) and that a longer request is rejected rather than silently truncated.
1 parent 9a3ea26 commit 0214cc4

2 files changed

Lines changed: 3 additions & 2 deletions

File tree

‎src/commands/interaction/metadata.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ const interactionCommandDescriptions = {
6868
'Move input focus to explicit screen coordinates without entering text. Prefer semantic interactions when a snapshot ref or selector is available; use type or fill after focus.',
6969
type: 'Append text to the currently focused input. Use fill when the existing field value should be replaced, and focus first when no input is active.',
7070
scroll:
71-
'Scroll in a direction, or toward the top/bottom edge of scrollable content. The optional amount is the finger-path fraction of the viewport axis; app scroll physics determine the final content offset.',
71+
'Scroll in a direction, or toward the top/bottom edge of scrollable content. The optional amount is the finger-path fraction of the viewport axis; the gesture releases with reduced momentum rather than stopping at an exact offset, so app scroll physics determine where content actually lands.',
7272
get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
7373
is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
7474
find: 'Find by text/label/value/role/id and run action',

‎website/docs/docs/commands.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -483,7 +483,8 @@ Target-authored drag is supported on Android touch devices and iOS/iPadOS. Backe
483483
`gesture transform` accepts `x y dx dy scale degrees [durationMs]` for one combined two-finger pan/zoom/rotate gesture on Android and iOS simulators. Pinch, rotate, two-finger pan, and transform use the same viewport-aware pointer planning; impossible paths fail before injection instead of clamping or distorting the requested motion.
484484
On iOS simulators it uses private XCTest synthesis for a continuous two-finger pan/scale/rotation path, so verify app-level metrics instead of assuming the requested values map exactly to recognizer output.
485485
On Android, `gesture transform` injects a geometric two-finger path. App recognizers may report non-exact pan, scale, and rotation values, so verify qualitative state such as `pan changed yes`, `pinch changed yes`, and `rotate changed yes` unless the app explicitly promises exact centroid metrics. If exact app-state values matter, prefer isolated `gesture pan`, `gesture pinch`, or `gesture rotate` commands.
486-
`scroll` accepts either a relative amount (`0.5` means a finger path spanning half of the viewport on that axis) or `--pixels <n>` for a fixed-distance gesture. The final content offset can differ because apps apply pan-recognition thresholds, collapsing headers, bounds, and their own scroll physics. Large distances are clamped to the usable drag band so the gesture stays reliable across Android, iOS, and macOS.
486+
`scroll` accepts either a relative amount (`0.5` means a finger path spanning half of the viewport on that axis) or `--pixels <n>` for a fixed-distance gesture. It releases with reduced momentum toward the requested distance, not an exact stop there — the final content offset can still differ because apps apply pan-recognition thresholds, collapsing headers, bounds, and their own scroll physics. Large distances are clamped to the usable drag band so the gesture stays reliable across Android, iOS, and macOS.
487+
On Android, a plain `scroll <direction>` releases in this reduced-momentum ("controlled") mode by default — it appends a short braking tail after the drag so the list does not fling past the requested distance — while `scroll top`/`scroll bottom` release inertially instead, coasting to the edge. That braking tail needs headroom within Android's 10000ms gesture ceiling, so a controlled scroll's own `--duration-ms` accepts at most 9840ms; a longer request is rejected with `INVALID_ARGS` rather than silently shortened or losing the braking tail.
487488
Default snapshot text output is visible-first, so off-screen interactive content is summarized instead of shown as tappable refs.
488489
When a target only appears in an off-screen summary, use `scroll <direction> --settle`: the response waits for the UI to go quiet and returns the diff against the tree you last observed, with fresh refs on the added lines, so no follow-up `snapshot -i` is needed. `back --settle` does the same for navigation. Both are best-effort and never fail the action. For repeated checks without settle, a small shell loop is enough:
489490

0 commit comments

Comments
 (0)