Skip to content

Latest commit

 

History

History
118 lines (90 loc) · 5.21 KB

cli.md

File metadata and controls

118 lines (90 loc) · 5.21 KB

Quick start: Command line

Start a session on a device, launch Settings, tap a row, take a screenshot, and quit — from the command line. Starts with mobium session start --platform android --app com.android.settings; ends with mobium session end.

Before this page: install mobium and prepare a device.

1. What you need

Nothing beyond mobium itself on your PATH.

2. The code

Save this as quickstart.sh — it is examples/cli/quickstart.sh.

#!/bin/sh
# Mobium quick start from the command line: start a session, drive Settings,
# quit.
#
#   MOBIUM_PLATFORM=android sh quickstart.sh    # or ios
set -e
PLATFORM="${MOBIUM_PLATFORM:-android}"
if [ "$PLATFORM" = ios ]; then
  APP=com.apple.Preferences ROW=General NEXT="label=About,role=button"
else
  APP=com.android.settings ROW="Network & internet" NEXT="text=Airplane mode"
fi
# With one device running, no --device is needed; MOBIUM_DEVICE picks one of several.
if [ -n "$MOBIUM_DEVICE" ]; then set -- --device "$MOBIUM_DEVICE"; else set --; fi

# 1. Start the session: the driver is started on the device and Settings is
#    launched. Every command after it uses this session. Quit it however the
#    script ends.
mobium session start --platform "$PLATFORM" --app "$APP" "$@"
trap 'mobium session end "$@"' EXIT

# 2. Map the screen: every element you can act on, each with a @ref.
mobium map "$@" | head -5

# 3. Tap a row by its ref, then wait for the screen it opens. A row's label can
#    carry its summary too ("Network & internet Mobile, Wi-Fi, ..."), so match
#    its start: the label begins right after the ref.
REF=$(mobium map "$@" | awk -v row="$ROW" 'index($0, $1 " " row) == 1 {print $1; exit}')
mobium tap "$REF" "$@"
mobium wait "$NEXT" "$@"

# 4. Take a screenshot.
mobium screenshot -o "quickstart-$PLATFORM.png" "$@"

Settings is on every Android and iOS device with nothing to install. The row and the screen after it are the only things that differ by platform.

3. Run it

Android

MOBIUM_PLATFORM=android sh quickstart.sh

What it printed on an Android 17 emulator:

waiting for the UiAutomator2 server to start...
session started on emulator-5556 (android, uiautomator2); com.android.settings was launched fresh and is in the foreground
@e1 Search Settings (button)
@e2 main_content_scrollable_container (list)
@e3 Google Services & preferences (button)
@e4 Network & internet Mobile, Wi‑Fi, hotspot (button)
@e5 Connected devices Bluetooth, pairing (button)
tapped @e4 at (540, 713)
text=Airplane mode is visible after 1.156s — @e5 Airplane mode (switch, unchecked)
saved /tmp/quickstart/quickstart-android.png (131411 bytes)
session ended on emulator-5556; anything it changed for the session is put back; com.android.settings, which the session launched, was stopped
After start After the tap
Settings, as start left it The screen the tap opened

iOS

MOBIUM_PLATFORM=ios sh quickstart.sh

What it printed on an iOS 27.0 simulator:

waiting for WebDriverAgent to start...
the simulator is on its home screen: a new session starts WebDriverAgent, whose runner takes the foreground and leaves it to the home screen, not to the app that was in front — app_launch brings an app back...
session started on B2580DC0-1C76-4B2E-ADD3-802A58033078 (ios, wda); com.apple.Preferences was launched fresh and is in the foreground
@e1 com.apple.settings.sidebar.collectionView (list)
@e2 Apple Account, Sign in to access your iCloud data, the App Store, Apple services, and more. (button)
@e3 Optimizing Search and Siri (button)
@e4 General (button)
@e5 Accessibility (button)
tapped @e4 at (603, 1219)
label=About,role=button is visible after 447ms — @e2 About (button)
saved /tmp/quickstart/quickstart-ios.png (309298 bytes)
session ended on B2580DC0-1C76-4B2E-ADD3-802A58033078; anything it changed for the session is put back; com.apple.Preferences, which the session launched, was stopped
After start After the tap
Settings, as start left it The screen the tap opened

The first start on a device is slow: it installs the UiAutomator2 server on Android, and on a real iPhone builds WebDriverAgent. Later starts take seconds.

Notes

  • Every command after session start uses that session, so none of them needs --driver. With more than one device attached, pass the same --device to each.
  • mobium session status lists the sessions open. mobium daemon stop ends all of them at once.
  • With more than one device of the session's platform running — two Android devices, or two among the booted simulators and attached iPhones — start refuses to guess and lists them. One Android device and one iOS device are not ambiguous: the platform picks. Name one with MOBIUM_DEVICE=<serial or UDID>, which the example passes on as the device.

Next: the rest of the tool surface, and setting up phones and simulators. Changing the client itself? DEVELOPMENT.md is the contributor's guide.