iOS Simulator: UI Tree
ios_simulator_ui_treeGet a flat list of on-screen controls with their labels, identifiers, and tap coordinates, filtered by type or text, to locate elements for tapping in the iOS simulator.
Instructions
List the addressable elements on screen — type, label, accessibility identifier, and the exact point to tap — flattened rather than nested. Prefer this over reading coordinates off a screenshot whenever you can: a label or identifier survives the screen moving, and a pixel position does not. The raw hierarchy is tens of KB, so this returns controls only by default; use contains or types to narrow further and detail to widen. A short answer is not proof the screen is bare — check the filtered field, which counts what the filters left out and names the argument that brings it back. Coordinates are in points, the same space ios_simulator_tap takes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| types | No | Keep only these element types, without the `XCUIElementType` prefix, e.g. ["Button", "Cell"]. | |
| detail | No | How much of the hierarchy to return. `interactive` (default) is controls only — buttons, cells, fields, switches — and is what you want to decide where to tap. `labelled` adds text and images that carry a label, for reading the screen's content. `all` is every visible node and is usually far too large to be useful. | interactive |
| device | No | Which simulator: its UDID or its name as shown by ios_simulator_list. Omit it when exactly one is booted — that is the normal case, and IOS_SIMULATOR_ID pins it when it is not. Unlike simctl's own `booted`, this never picks arbitrarily between two. | |
| contains | No | Keep only elements whose label, identifier or value contains this, case-insensitively — e.g. "Today". | |
| include_invisible | No | Include elements XCUITest marks as not visible. Off by default, because on a scrolling list they outnumber the visible ones many times over — but the flag is not always truthful: a photo picker and a share sheet report their own contents as invisible while they are on screen and respond to a tap. Turn this on when `filtered.notVisible` says something was left out and the screen plainly has more on it than came back. |