Skip to main content

map · map_diff

This tool on every surface: CLI · MCP · Python · JavaScript · Go · Java · .NET

Map the actionable elements on the current screen and return them as refs (@e1, @e2, ...) with a label and role. These call app_map.

map​

def map() -> list[Element]

Actionable elements on the current screen.

Refs are only valid for this screen; call map() again after anything that changes it.

map_diff​

def map_diff() -> dict[str, Any]

What the screen did since the last map of this device: the elements that appeared, went away, or changed their label, checked or selected state, value or place. Map, act, then map_diff() says what the action just did.

Returns a dict with added and removed as lists of the same Elements map() returns, changed as a list of dicts with before and after Elements and what changed (label, checked, selected, disabled, value, moved or resized), since as the time of the map compared with, and first true when there was no earlier map to compare with — then the whole screen is in added. Refs are the new map's, so an added or changed element can be acted on at once; a removed element's ref is stale.

Examples​

Map what can be acted on, with a ref for each​

for el in device.map():
    print(el.ref, el.label)

The same call from the command line, mobium map, printed on an Android 15 emulator:

@e1 settings_homepage_container (list)
@e2 Profile picture, double tap to open Google Account (button)
@e3 Search settings (button)
@e4 main_content_scrollable_container (list)
@e5 Network & internet Mobile, Wi‑Fi, hotspot (button)
@e6 Connected devices Bluetooth, pairing (button)
@e7 Apps Assistant, recent apps, default apps (button)
@e8 Notifications Notification history, conversations (button)
@e9 Battery 100% (button)
@e10 Storage 51% used - 7.85 GB free (button)
@e11 Sound & vibration Volume, haptics, Do Not Disturb (button)

mobium map on an Android 15 emulator

mobium map on an Android 15 emulator

What the last action changed​

diff = device.map_diff()
for e in diff["added"]:
    print("+", e.ref, e.label)
for c in diff["changed"]:
    print("~", c["after"].ref, c["after"].label, c["what"])