await-ui-element
Block until a UI element reaches an expected state (exists, visible, hidden, or contains text) or a timeout elapses, so you don't have to poll manually.
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 VISIBLE match in reading order (topmost, then leftmost; falling back to the first match
overall if none is visible) contains expectedText (case-insensitive substring), or exactly matches
it when textMatch is equals. A loose selector can match several elements; only that one is
inspected, so if a different 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. text and role match as
case-insensitive substrings of the element's label/value and role; identifier matches exactly (case-insensitive),
also accepting the unqualified Android resource-id name ('submit' matches 'com.example.app:id/submit').
It polls the same accessibility / DOM tree as describe
(iOS AXRuntime, Android uiautomator, Chromium CDP, Vega automation toolkit) 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 visible match in reading order (topmost), falling back to the first match overall if none is visible, contains (or, with textMatch `equals`, exactly matches) expectedText — if a loose selector hits several elements, only that one is checked, so narrow it to target the intended element. | |
| textMatch | No | For condition `text`: how expectedText is compared. `contains` (default) is a case-insensitive substring; `equals` is a case-insensitive full-string match. | |
| timeoutMs | No | Max time to wait for the condition before giving up (default 5000). | |
| expectedText | No | For condition `text`: the string the first visible matched element (topmost in reading order; the first match overall if none is visible) must contain (default) or equal — see `textMatch`. Case-insensitive. | |
| pollIntervalMs | No | How often to re-check the tree (default 400). |