tap_element
Taps a resolved UI element by its elementId. Returns execution status; verify outcome separately.
Instructions
Purpose: Tap a previously resolved UI element using its elementId.
Inputs:
elementId: a resolved UI element identifier returned by wait_for_ui
Output Structure:
action_id: unique timestamp-based action identifier
timestamp: ISO 8601 timestamp for the action attempt
action_type: "tap_element"
lifecycle_state: post-dispatch lifecycle state (pending_verification or failed)
source_module: runtime source of the action envelope
target.selector: original target handle ({ elementId })
target.resolved: minimal resolved element info used for the tap
success: true when the tap was dispatched
failure_code: present when success=false
retryable: present when failure_code exists
ui_fingerprint_before/ui_fingerprint_after: optional fingerprints captured around the action
Recommended Usage:
Resolve the target with wait_for_ui or another deterministic resolver
Call tap_element
If needed, wait for transition using wait_for_*
Verify outcome using expect_*
use expect_screen when navigation is expected
use expect_element_visible when the UI change is local
If verification fails, inspect failure_code and follow the retry strategy below
Verification Guidance:
Follow RESOLVE → ACT → WAIT (if needed) → EXPECT
Prefer expect_screen for navigation or modal transitions
Prefer expect_element_visible when the tap should reveal or update a specific element
wait_for_* may be used for resolution and synchronization, but not as the final verification step when an applicable expect_* tool exists
Do not treat tap_element.success as outcome success; it only means the tap was executed
Failure Handling:
STALE_REFERENCE → re-resolve the element, then retry
ELEMENT_NOT_INTERACTABLE → wait or refine the target, then retry
UNKNOWN → capture a snapshot and stop
This tool reports execution success only. Verification must be done with a separate expect_* tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| elementId | Yes | A unique element identifier returned by wait_for_ui |