auto-mobile-usage

Driving devices with AutoMobile

1. Get a session first

• Acquire a device with getAndroid or getApple. It finds or boots one and returns a sessionUuid.
• A connection that acquired a device is bound to it, so later calls route to that session without repeating it. A different connection, or a CLI call, passes sessionUuid on every call.
• A device that a session holds takes control calls only from that session (device_owned_by_other_session otherwise). Naming someone else's sessionUuid never takes the device over.
• setActiveDevice and acquisition are the only calls that change which session an untargeted call uses. With several sessions, pass sessionUuid or deviceId (ambiguous_session_selector).
• session_ownership_lost and no_active_device_session are permanent for that session: acquire a new one.

2. Observe before you act

• Call observe before the first action and again after each action that can change the screen. Coordinates and Android synthetic s2- element ids are valid only for the observation that returned them.
• Act on what observe returned: tapOn takes a selector (text, elementId, testTag), swipeOn scrolls the screen or a container (lookFor scrolls until an element appears), tapAt takes coordinates, sendKeys types into the focused field. Do not guess coordinates.
• skeleton lists only rows you can act on. Static text (a status label, a validation error, a result message) is in context; read it there to verify a result. waitFor with text or textAny, or for: "appear"/"textEquals" with only text, matches text in either array.
• Ask observe for a screenshot only when the hierarchy is not enough; images are the largest part of a result.

3. Resources versus tools

• Tools act or run a computation. Resources (automobile: URIs) are cheap read-only state: automobile:tools lists every tool and whether it is enabled, automobile:devices/booted lists booted devices, automobile:observation/latest is the latest observation.
• Read a resource instead of calling a tool when you only need state. A sessionless read never takes a held device.
• A tool that is gated off does not appear in tools/list. Enable it with setToolEnabled or the enableTools argument of getAndroid and getApple.