await-ui-element
Wait for a UI element to reach an expected state—exists, visible, hidden, or text—and stop polling manually. Use after navigation or before interacting with asynchronous elements.
Instructions
Block until a UI element reaches an expected state or a timeout elapses, so you don't have to poll screenshot/describe yourself.
Conditions: exists — the selector matches an element anywhere in the tree. visible — the selector matches an element with a non-zero on-screen frame. hidden — the selector matches nothing, or only a zero-area element (e.g. a spinner that disappeared). text — the FIRST match in reading order (topmost, then leftmost) contains expectedText (case-insensitive substring). A loose selector can match several elements; only that topmost one is inspected, so if a lower match is the one holding the text the wait still reports failure — narrow the selector to target it.
The selector is { text?, identifier?, role? }; every provided field must match (case-insensitive substring).
text matches the element's label or value. It polls the same accessibility / DOM tree as describe
(iOS AXRuntime, Android uiautomator, Chromium CDP) every pollIntervalMs (default 400ms)
until timeoutMs (default 5000ms).
Returns { success: boolean, elapsed: number } — success=false means the condition never held before the
timeout (a note then explains what was seen). Use this after a tap/navigation to wait for the next screen,
or before tapping an element that appears asynchronously.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| udid | Yes | Target device id from `list-devices` (iOS UDID, Android serial, or Chromium id). | |
| bundleId | No | Optional iOS app bundle id, passed to the describe fallback (see `describe`). Ignored on Android / Chromium. | |
| selector | Yes | Element to match (text / identifier / role). | |
| condition | Yes | What to wait for. `exists`: selector is anywhere in the tree. `visible`: selector is present with a non-zero on-screen frame. `hidden`: selector is absent or zero-area. `text`: the first match in reading order (topmost) contains expectedText — if a loose selector hits several elements, only that topmost one is checked, so narrow it to target the intended element. | |
| timeoutMs | No | Max time to wait for the condition before giving up (default 5000). | |
| expectedText | No | For condition `text`: case-insensitive substring the first matched element (topmost in reading order) must contain. | |
| pollIntervalMs | No | How often to re-check the tree (default 400). |