Check that this machine can drive an iOS device, and say how to fix what it can't.

Run this first when a session fails to start, when a device does not appear, or after an Xcode or iOS upgrade. Every failing check comes with a concrete remedy.

List iOS Simulators and attached physical iPhones available for automation.

ready is false when something blocks automation; blockers says what.

Attach to a device and start driving it.

Boots the simulator or verifies the phone, starts WebDriverAgent, and opens a tuned session. Omitting device prefers an already-booted simulator over a connected iPhone, so acting on a real device is always a deliberate choice.

Report the current session: device, foreground app, and safety state.

Release the device and shut down its WebDriverAgent runner.

List apps installed on the device, with their bundle identifiers.

Bring an app to the foreground and return its screen.

Force-quit an app.

Open a URL or deep link.

Usually the cheapest way to reach a screen: a deep link skips the navigation an agent would otherwise have to tap through.

Install an app from a local .app or .ipa.

Read the screen as a compact list of elements with short refs.

Each line is one element: e7 button "Send" @(340,70). Pass those refs to the action tools rather than coordinates.

If the result says elements were omitted, narrow with query or region instead of raising budget; a smaller answer is usually the more useful one.

Capture the screen as an image.

Use this when an element has no accessibility label, when the layout matters, or when ios_observe cannot find something you can plainly see. With annotate_refs each element is boxed and labelled with its ref, so you can pick one by eye and pass it to an action tool.

Annotating re-reads the screen first, so the refs on the image are the current ones rather than whatever was observed last. That costs a tree fetch, and needs the vision extra installed.

Read the text of the screen, or of one element and everything inside it.

Use this to extract content, rather than ios_observe, which is shaped for deciding what to tap.

Search the screen's accessibility tree, including what the digest hides.

Prefer ios_observe with a query when you want a usable digest you can tap from: what it returns carries refs. Use this when ios_observe shows nothing matching but the text is on the device, or when a tap keeps missing. It reads the tree before compaction, so it reports matches the digest dropped, which ios_observe by construction cannot, and each one says whether it is shown or hidden. A hidden match is the diagnosis: the words are on screen and perception is why you cannot reach them. Name it by the id reported here.

Wait for something to appear or disappear.

Prefer this over guessing a sleep. It returns as soon as the condition holds, and reports failure rather than raising, so a timeout is something you can reason about.

Read recent device logs. Useful when an app misbehaves and the UI does not say why.

Return the ordered record of everything this session has done.

Useful for explaining what happened, and for turning a successful run into a regression test.

Tap an element and return the resulting screen.

Prefer ref over target; it is exact and cannot be misread. Taps on things like Send, Pay, or Delete need approval first.

Type into a field, focusing it first when a ref or target is given.

The field is read back afterwards. If the text did not land, the call fails with typed.shown saying what the field holds; reformatted means it landed with the app's own capitalisation or formatting.

Type a stored secret without ever seeing its value.

The value is read from the host keychain and sent straight to the device. Use this for every password and one-time code; never put a real credential into ios_type, where it would enter the transcript.

Set a switch, slider, or picker wheel to a value.

'on' or 'off' for a switch, a percentage such as '40%' or a fraction for a slider, and the option spelled the way the wheel spells it for a picker. A wheel is turned a row at a time and read back after each one, so an option it does not contain fails listing what it does.

Prefer this over tapping a switch: it checks the current state first, so asking for 'on' when it is already on does nothing rather than turning it off.

Steppers and segmented controls are not set this way. iOS reports their parts and the digest shows them, so tap 'Increment', 'Decrement', or the segment by its own label.

Scroll, optionally until some text comes into view.

With until, this stops as soon as the text appears and gives up when the content stops moving, so it will not spin at the end of a list.

Swipe once, for carousels, page views, and swipe-to-reveal rows.

Drag one element onto another, for reordering lists and moving items.

Press a hardware button or a keyboard key.

Answer a system alert.

Read the alert text before choosing. Accepting blindly is how an agent grants a permission or confirms a deletion nobody wanted.

Stop this session from taking further action.

Clear a halt after a human has decided it is safe to continue.

Set a privacy permission without going through the alert.

Simulator only. On a real phone there is no API for this: drive the Settings app, or answer the permission alert with ios_handle_alert.

Read or write the device clipboard.

Writing is often faster and more reliable than typing a long string, which the on-screen keyboard can mangle with autocorrect.

Change device-level state. Appearance, location, and status bar are Simulator only.