detect_ui_change
Detects UI changes on Android devices after user actions by comparing screen states. Use to verify interactions, wait for transitions, and confirm expected screen updates during automated testing.
Instructions
Polls the UI hierarchy after an action and returns when the screen content changes or the timeout is reached. Returns changed status and elapsed time. By default, omits the XML hierarchy for efficiency — set return_hierarchy=True to receive the full hierarchy.
For efficient change detection: call snapshot_ui before the action, perform the action, then call detect_ui_change with baseline_token. Only use without baseline_token when you need to wait for a slow transition (loading screens, animations). Do not use to read the current screen state — use get_ui_hierarchy for that.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timeout_seconds | No | Maximum seconds to poll for a UI change. | |
| baseline_token | No | Token returned by snapshot_ui, captured before the action. When provided, compares current UI against that snapshot — use this for reliable change detection without loading XML into context. When omitted, captures a fresh baseline at call time. | |
| return_hierarchy | No | When False (default), returns only changed and elapsed_seconds — no XML. Set to True to include the full UI hierarchy in the response. Only set True when you need to read element data immediately after the change. | |
| device_serial | No | Android device serial (e.g. 'emulator-5554' or '192.168.1.10:5555'). Omit only when a single device is connected. If the tool returns a multi-device error: STOP. Present the device list to the user verbatim and wait for their explicit choice. Do NOT retry with a guessed or inferred serial — this is a hard requirement. Once the user provides a serial, use it for every subsequent call in this session. To switch devices mid-session, ask the user first. |