scroll_to_element
Scroll through a mobile app screen until a target element is located. Helps find elements not initially visible on Android or iOS.
Instructions
Purpose: Scroll until a target element becomes visible.
Inputs:
platform
selector
direction, maxScrolls, scrollAmount, deviceId (optional)
Output Structure:
action_id, timestamp (ISO 8601), action_type
lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
source_module: runtime source of the action envelope
target.selector = original selector
target.resolved = minimal resolved element info when found
success = true when scrolling produced a visible target element
failure_code/retryable when the target was not reached
ui_fingerprint_before/ui_fingerprint_after when available
Recommended Usage:
Resolve the target selector
Call scroll_to_element
If needed, wait for UI stabilization using wait_for_*
Verify with expect_element_visible when the expected element visibility is known
If success=false, follow failure handling before retrying
Verification Guidance:
Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
Use expect_element_visible when you need an explicit post-scroll confirmation
Do not use wait_for_* alone as final verification when an applicable expect_* tool exists
Failure Handling:
NAVIGATION_NO_CHANGE → adjust scroll direction or stop
TIMEOUT → retry with refined selector or larger scroll budget
UNKNOWN → capture a snapshot and stop
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| deviceId | No | Device UDID (iOS) or Serial (Android). Defaults to booted/connected. | |
| platform | Yes | Platform to operate on (required) | |
| selector | Yes | ||
| direction | No | down | |
| maxScrolls | No | ||
| scrollAmount | No |