Docs / Operation reference / android operations

android operations#

32 operations. Generated from assets/operations.json; all areas.

android.screen#

Android screen preview

Save an Android device's screen as a PNG at path at once, through adb exec-out screencap, within 10 seconds and without a job, for previews that refresh such as the desktop's device grid. The result has the file's size and the picture's width and height. For evidence kept with a job, use device.capture.

Annotations: writes, idempotent, open world.

tomaccoctl call android.screen '{"device":"<device>","path":"<path>"}'

android.store_screenshots#

Capture store screenshots

Capture store screenshots of an installed Android app as a job: on each device, for each app language (set with android.settings app_locale, Android 13 and newer) and each of light and dark mode, every screen in order: stop and launch the app, run the screen's testing.run steps, wait settle_ms and save the screen. Files go to DIRECTORY/THEME/LOCALE/images/KIND/NN_SCREEN.png, where KIND is phoneScreenshots, sevenInchScreenshots or tenInchScreenshots by the device's smallest width, so each THEME folder is a fastlane supply metadata directory. Animations are off while capturing; each device's dark mode, animations and app language are put back afterwards. report.json lists every file with its size and play_problems (a side under 320 or over 3840 pixels, or longer than 2:1).

Annotations: writes, not idempotent, open world.

tomaccoctl call android.store_screenshots '{"bundle_id":"<bundle_id>","devices":["<device>"],"locales":["<locale>"],"screens":[{"name":"<name>"}],"directory":"<directory>"}'

android.input#

Tap / swipe / input

Control real Android UI through adb, using device pixel coordinates. ASCII text is typed; other text is pasted through the device clipboard with the configured scrcpy 4.1 server on Android 7 and newer.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.input '{"device":"<device>","action":"tap"}'

android.hierarchy#

Read UI tree

Read Android's UIAutomator XML hierarchy.

Annotations: read-only, idempotent, open world.

tomaccoctl call android.hierarchy '{"device":"<device>"}'

android.launch#

Start Android activity

Resolve the installed launcher activity and wait for the actual launch result.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.launch '{"device":"<device>","bundle_id":"<bundle_id>"}'

android.record#

Record display

Record an Android screen video and pull it to the given path, as a job. job.send stop ends the recording early and still pulls the video.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.record '{"device":"<device>","path":"<path>"}'

android.mirror#

Show Android live

Open scrcpy with keyboard and pointer control for the selected device.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.mirror '{"device":"<device>"}'

android.deep_link#

Open deep link

Open a deep link on the selected Android device.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.deep_link '{"device":"<device>","url":"<url>"}'

android.performance#

Performance report

Collect actual memory, frame timing, battery or package reports.

Annotations: read-only, idempotent, open world.

tomaccoctl call android.performance '{"device":"<device>","bundle_id":"<bundle_id>"}'

android.ports#

Connect dev server

Create/remove adb reverse or forward TCP ports.

Annotations: writes, idempotent, open world.

tomaccoctl call android.ports '{"device":"<device>","local_port":1,"device_port":1}'

android.permission#

App permission

Grant or revoke a runtime permission for a selected app.

Annotations: writes, idempotent, open world.

tomaccoctl call android.permission '{"device":"<device>","bundle_id":"<bundle_id>","permission":"<permission>"}'

android.settings#

Device settings for tests

Read or set what changes an app's look and motion in UI tests and screenshots: dark mode, font scale, animations, airplane mode and one app's language. Arguments left out stay as they are; the result reads every setting back and reports a value Android did not apply as setting_not_applied.

Annotations: writes, idempotent, open world.

tomaccoctl call android.settings '{"device":"<device>"}'

android.display#

Display orientation and size

Lock the screen orientation, override the display size or density, or reset them, on a phone or emulator; the result reads all three back. A value Android did not apply answers setting_not_applied. With no other argument it only reads.

Annotations: writes, idempotent, open world.

tomaccoctl call android.display '{"device":"<device>"}'

android.notifications#

Notifications

List the notifications Android is showing, with key, package, title, text, channel and flags; open or close the notification shade; or snooze one notification by its key. Every action returns the list afterwards. adb cannot cancel another app's notifications, so snooze hides one for a time instead.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.notifications '{"device":"<device>"}'

android.app_files#

App data files

List or pull the private files of a debuggable app (its data directory, through run-as). pull returns a job that writes the files as one .tar archive. Release builds answer app_not_debuggable. To clear app data or force-stop the app, use device.app.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.app_files '{"device":"<device>","bundle_id":"<bundle_id>"}'

android.each#

Run on every Android device

Run the same steps on every connected Android device, or on the listed ones, as one job: all devices at once, each device's steps in order until one fails. A step that returns a job is followed to its end. The job's report.json artifact has every device's result; the job fails if any device failed. Steps leave out device and platform, which are set per device.

Annotations: destructive, not idempotent, open world.

tomaccoctl call android.each '{"steps":[{"operation":"device.install"}]}'

android.connect#

Android over Wi-Fi

Pair or connect adb to a device address. Pairing codes are not persisted.

Annotations: writes, idempotent, open world.

tomaccoctl call android.connect '{"address":"<address>"}'

android.pair#

Pair over Wi-Fi by QR code

Wireless debugging pairing by QR code, for Android 11 and newer. action qr makes a one-time service name and password and returns the QR code the phone's Developer options > Wireless debugging > Pair device with QR code scans: qr_text, the modules as qr.rows (1 is dark), an SVG, and with path a PNG or SVG file. Nothing is stored. action wait, with that service and password, waits up to timeout seconds for the phone to offer the code on the local network (adb mdns), pairs with adb pair and connects to the phone's debugging service; the result names the device to use. Call wait again while the code shows; pairing_timeout means the phone has not scanned it yet. action services lists what adb finds on the network, such as the address the phone shows under Pair device with pairing code, for android.connect with pairing_code.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.pair

android.calibrate#

Read model from device

Create a custom profile from actual wm size/density. Frame details remain editable.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.calibrate '{"device":"<device>","profile_id":"<profile_id>","name":"<name>"}'

android.sdk_packages#

SDK packages

List available/installed Android SDK packages.

Annotations: read-only, idempotent, open world.

Takes no arguments.

tomaccoctl call android.sdk_packages

android.sdk_install#

Install SDK packages

Install explicit SDK package IDs. License acceptance is opt-in.

Annotations: writes, idempotent, open world.

tomaccoctl call android.sdk_install '{"packages":["<package>"]}'

android.avds#

Android emulators

List configured Android emulators with model profile, resolution, density, GPU mode and installed system images. Legacy profiles are inferred only from unique resolution/density matches.

Annotations: read-only, idempotent, open world.

Takes no arguments.

tomaccoctl call android.avds

android.avd_create#

Create emulator

Create an AVD using an installed system image and a catalogue profile.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.avd_create '{"name":"<name>","system_image":"<system_image>","profile_id":"<profile_id>"}'

android.avd_profile#

Set emulator display

Apply a profile's resolution/density to a stopped Tomacco AVD. On a host with less than 10 GiB of memory or at most 4 processors it also lowers the emulator's memory and processors (adapted_to_host), unless android.avd_configure set them.

Annotations: destructive, idempotent, open world.

tomaccoctl call android.avd_profile '{"name":"<name>","profile_id":"<profile_id>"}'

android.avd_configure#

Set emulator performance

Persist graphics, RAM and CPU settings for a stopped registered Android emulator. Preserves app data and other configuration, saves the original configuration, and skips incompatible VM snapshots on subsequent Tomacco starts. Running AVDs are rejected.

Annotations: writes, idempotent, open world.

tomaccoctl call android.avd_configure '{"name":"<name>"}'

android.avd_start#

Start emulator

Start or reuse an Android virtual device. A Tomacco-managed AVD resumes from its Quick Boot snapshot when android.emulator saved one at its last stop; the result's boot says quick or cold and why. CPU acceleration remains enabled independently of the selected GPU renderer. A start with a window needs X11 (DISPLAY, XWayland on Wayland) and is refused with emulator_no_display without it; the emulator gets QT_QPA_PLATFORM=xcb when the session names only wayland. With gpu configured and the AVD's default auto renderer, a host without a hardware GPU driver starts with swiftshader (gpu in the result says so).

Annotations: writes, idempotent, open world.

tomaccoctl call android.avd_start '{"name":"<name>"}'

android.emulator#

Control emulator

Stop an emulator, saving the Quick Boot snapshot of a Tomacco-managed one so its next start resumes in seconds; save, load, list or delete its snapshots; set its GPS location, battery or network speed and latency through the emulator console. A command the console refuses answers emulator_refused.

Annotations: destructive, not idempotent, open world.

tomaccoctl call android.emulator '{"device":"<device>","action":"stop"}'

android.package_inspect#

Inspect APK or AAB

Read an APK or AAB without a device: package, version name and code, minimum, target and compile SDK, permissions, native ABIs and signing certificates with their SHA-256 digests. APKs go through aapt2 and apksigner from the SDK build-tools; an AAB's manifest is read directly and its signature through keytool. Reads the file only.

Annotations: read-only, idempotent, closed world.

tomaccoctl call android.package_inspect '{"path":"<path>"}'

android.size_report#

Report APK or AAB size

Break an APK or AAB down by size without a device: totals, each category (dex, native, resources, assets, manifest, signature), each ABI, screen density and bundle module, and the largest files. estimate.by_abi_density adds up the compressed sizes one device would get without other ABIs' libraries and other densities' resources. For an AAB with bundletool configured, download has bundletool get-size total's download size per ABI and density, from APKs it builds in a temporary directory. baseline compares with an earlier build: the change of every total and the files that grew, shrank, appeared or went away the most.

Annotations: read-only, idempotent, open world.

tomaccoctl call android.size_report '{"path":"<path>"}'

android.sensors#

Emulator sensors

Simulate the sensors of an Android emulator through its console. status lists every sensor with its values; set gives one sensor values; orientation turns the device by gravity and reads back the display rotation Android chose; shake shakes the accelerometer for about a second; proximity covers or uncovers the proximity sensor; light sets the ambient light; fingerprint touches the fingerprint sensor with an enrolled finger, for a biometric prompt; posture folds, half-opens or opens a foldable emulator.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.sensors '{"device":"<device>","action":"status"}'

android.app_links#

App Links

Check an app's Android App Links. status reads each web domain the app declares with autoVerify and its verification state (verified, none, denied, or the verifier's error code) and the user's link choices; verify asks Android to verify the domains again and waits up to seconds for the answers, which need the domains' assetlinks.json and a network; resolve names the app and activity a link opens, or that Android shows a chooser, and every app that could open it; set approves, denies or resets domains by hand, as tests of a debug build need. Opening a link is android.deep_link.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.app_links '{"device":"<device>"}'

android.network_capture#

Network capture

Capture the network traffic of an emulator, or only what one app sends, and summarise it: hosts with bytes and connections, TLS server names, HTTP requests with method, host and path but no query, and DNS queries. Contents are never in the summary; HTTPS stays encrypted, as no certificate is installed. start needs opt_in:true, a running emulator whose image allows root through su (Google APIs or AOSP, not Google Play) and runs the image's tcpdump; bundle_id limits it to the app's outgoing packets through an iptables rule that stop removes. stop ends it, copies the pcap file, readable only by you, to path and summarises it; summary reads any pcap file.

Annotations: writes, not idempotent, open world.

tomaccoctl call android.network_capture '{"action":"start"}'

View this page as Markdown on GitHub