Reference
device_press
Tap a UI element by its @ref from device_snapshot, or at explicit raw x/y coordinates. Exact raw control can operate without a managed Metro target and always labels meta.originAuthority as proven or not-proven; not-proven results are never strict source evidence. Pass exactly one target form. On iOS, a latest-snapshot Key/Keyboard ref is runner-validated against the current live keyboard and activated exactly once (meta.keyboardGuard=“keyboard_target”); stale, forged, missing-keyboard, or raw-coordinate targets never receive that exemption. Ordinary app-content taps dismiss only through a safe native hide/dismiss control or optional JS tier, then refresh and uniquely re-resolve before one tap. Supports double-tap, repeated taps, long hold, and post-tap focus settle. Requires an open session. Stale ordinary app @refs self-heal by identity re-resolution (meta.reResolved); stale iOS Key/Keyboard refs refuse with KEYBOARD_TARGET_STALE and mutation:none. A command is never replayed after a possible dispatch; uncertain Android effects fail with one-attempt typed uncertainty. On Android the tap is scoped to the owned app window: a @ref belonging to another package (system navigation, IME, dialogs) is refused with OUTSIDE_APP_WINDOW — use device_find with includeSystemUi=true and action=“click” for system UI.
Parameters
Section titled “Parameters”| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
ref | string | No | Element ref from device_snapshot (e.g. “e3” or “@e3”). Omit when using x/y. | ||
x | number | No | Raw tap X coordinate; requires y and no ref | ||
y | number | No | Raw tap Y coordinate; requires x and no ref | ||
doubleTap | boolean | No | Use double-tap gesture | ||
count | number | No | min: 1, max: 50, integer | Repeat tap N times (for rapid-fire interactions) | |
holdMs | number | No | min: 0, max: 10000, integer | Hold duration in ms (for long-press via ref) | |
waitForFocusMs | number | No | min: 0, max: 5000, integer | Sleep this many ms after tap to let keyboard focus settle — useful in sequential press+fill flows where focus would otherwise not propagate. | |
settleTimeoutMs | number | No | min: 500, max: 30000, integer | Override the post-action settle budget in ms (default 6000). Settle waits for the UI to stabilize after the action; see meta.settle in the result. Budget knob only — RN_SETTLE=0 disables settle. | |
retryIfNoChange | boolean | No | Deprecated compatibility option. Interactions are never automatically replayed after a possible dispatch; uncertainty is reported from the first attempt. |
device_press()