Test prep tools¶
Prepare a repeatable device and app state (fixtures, locale, permissions, system state) before running a flow.
App files¶
Use putAppFile to write text, base64, or a host file into an app container:
{
"name": "putAppFile",
"arguments": {
"platform": "android",
"target": {
"domain": "app_containers",
"appId": "com.example.app",
"container": "documents"
},
"files": [
{
"destinationPath": "fixtures/settings.json",
"contentText": "{\"enabled\":true}"
}
]
}
}
For large files, see MCP message size.
putAppFile never terminates the app. After an app_containers write,
result.warning says the app may not see the change until it re-reads the file
or relaunches. It appears only when AutoMobile knows the app is running (on
Android, in the written user profile), and never for other domains.
user_files on an iOS Simulator stages files through the managed Files fixture
app dev.jasonpearson.automobile.FilesFixture. Writes go only to
Documents/automobile/<namespace>, and reset deletes only that namespace. Without the fixture app, the call explains how to install it. A staged file may not show up in a document picker. Physical iOS devices and
listing or reading user files on iOS are not supported.
On Android, putAppFile accepts an optional userId (a non-negative integer) to
target a work or secondary profile. Without it, AutoMobile uses the only user the app is installed for. With several candidates it prefers the foreground app’s
user, then the current user. If that is still ambiguous, the error lists the candidate IDs for userId.
Private documents/cache/tmp containers require a debuggable app.
externalFiles writes to the app’s external files directory for the chosen user.
On API 30+, the platform may deny writes to other apps’ Android/data
directories. See File containers for semantics.
To list files, read the resource
automobile:devices/{deviceId}/storage-domains/app_containers/{appId}/{container}{?userId}.
To read a file, append /{path} before the query, for example:
automobile:devices/emulator-5554/storage-domains/app_containers/com.example.app/documents/settings.json?userId=10.
Returned file URIs include the resolved user (?userId=N) where it matters.
iOS URIs have no user query.
Locale and device state¶
changeLocalizationsets language, region, time zone, and formatting for a device. Set the locale before launching the app.setDeviceStateconfigures supported system state:- biometric enrollment;
- an Android lock-screen PIN, password, or pattern (
screenLock), which the session clears on release; - Android power constraints (
power: battery, battery saver, Doze, standby buckets, Data Saver, thermal status), which the session restores on release; - a camera poster (
cameraPoster); see Camera posters. biometricAuthsimulates a match or failure on supported emulators and iOS simulators, and every result in apps that embed the AutoMobile SDK.wakeAndUnlockwakes an Android device and unlocks it with an optional PIN.postNotificationcreates a notification for notification-flow tests. On a watchOS or Apple TV simulator, provide the app’s bundle ID asappIdto deliver a push to that app. A single iOS notification shows no app name, sosystemTraycan match it byappIdonly when it was posted withpostNotification; otherwise omitappId.clipboardsets, reads, pastes, or clears clipboard content.
Phone calls and SMS¶
phoneCall and sendSms are off by default; enable them before use.
| Device | phoneCall |
sendSms |
|---|---|---|
| Android emulator | All actions | Supported |
| Android physical | Not supported | Not supported |
| iOS Simulator + SDK | call, cancel, busy; accept/hold partial |
SMS-style notification from the app’s SDK |
| iOS physical | Not supported | Not supported |
On iOS the app under test must embed the AutoMobile iOS SDK; without it sendSms
and phoneCall call, cancel and busy fail and ask for the SDK.
If the app’s notification permission is undecided, the first iOS sendSms returns
notification_permission_pending and shows the system alert. Tap Allow, then call
sendSms again. notification_permission_denied means enable notifications in
Settings or reinstall/reset the app before retrying.
The iOS Simulator cannot answer or hold a CallKit call: its call service ends the
call instead. On a simulator, phoneCall with accept or hold sends nothing to
the app. It returns this result without an error, with or without the SDK or a
phoneNumber:
{
"success": false,
"supported": "partial",
"reason": "ios_simulator_callkit_limit",
"action": "accept",
"message": "The iOS Simulator cannot accept or hold a CallKit call: ..."
}
This is not a failure: check supported and reason, and drive the in-call state with call, cancel and busy. Every other failure
(missing phoneNumber, no SDK, an SDK rejection, an unsupported device) returns a
tool error.
Reaching a host server from the device¶
Use portReverse when an app on an Android device must reach a server on your
machine at http://localhost:<port>. See
Reaching a host server from the device for its actions,
probes, and error codes.
Camera posters¶
A camera poster puts an image or QR code in front of the camera. Physical iOS and Android devices, and Apple platforms other than iOS, do not support camera posters.
setDeviceState cameraPoster accepts mode: "image" with a host PNG/JPG/JPEG
path, mode: "qr" with text, or mode: "clear".
- Android emulators update the virtual-scene poster live (
surface: "wall"or"table"). - On iOS Simulator, the call records the poster for each app’s next
launchApp. It returnsmethod: "ios_simulator_dyld_injection",pathwhen set, andrelaunchRequired: true. Relaunch running apps; iOS ignoressurface. After clearing, uselaunchAppwithcoldBoot: trueto remove the poster from a running app.
startDevice accepts mutually exclusive cameraPosterPath or
cameraPosterQr: { text }. Android requires a stopped emulator; iOS Simulator also
accepts posters when already running.
On iOS, launchApp applies a registered poster with a cold launch and reports
cameraPosterApplied: true. Apple system apps (com.apple.*) launch without the poster and report cameraPosterApplied: false with a note in
message.
An iOS poster lasts until one of these happens:
- you clear it;
killDevicekills the simulator;- the session that holds the simulator is released or switches device;
- the daemon restarts.
A later session on the same simulator starts without a poster.
Setting an iOS poster needs Xcode. AutoMobile builds the injection library from the
packaged source on first use, for Intel and Apple silicon simulators. A missing
Xcode or library fails startDevice or setDeviceState and records nothing,
rather than failing the later launchApp. To skip the build, set
AUTOMOBILE_IOS_CAMERA_POSTER_DYLIB to a prebuilt library.
Clean start¶
For a clean app start, use launchApp with clearAppData: true where the
platform supports it. Then confirm the state with observe.
Device snapshots¶
Enable deviceSnapshot for the current connection, then capture a known-good
state before a destructive flow:
{
"name": "setToolEnabled",
"arguments": { "toolName": "deviceSnapshot", "enabled": true }
}
{
"name": "deviceSnapshot",
"arguments": {
"action": "capture",
"snapshotName": "signed-in",
"platform": "android",
"includeAppData": true,
"includeSettings": true
}
}
Android emulators can restore full VM snapshots. iOS simulators back up the specified app containers, so an iOS capture that includes app data must list the bundle IDs:
{
"name": "deviceSnapshot",
"arguments": {
"action": "capture",
"snapshotName": "signed-in",
"platform": "ios",
"appBundleIds": ["com.example.app"],
"includeAppData": true,
"includeSettings": true
}
}
For an iOS settings-only capture, set includeAppData to false. Physical
Android devices restore settings only. Restore with action: "restore" and the
same snapshotName.
An Android VM restore can return a new deviceSessionUuid. Your own sessionUuid
stays valid. If you subscribed to the old device-session UUID, you receive
device_session_ended with successorSessionUuid and
reason: "superseded-by-restore", followed by device_session_started; subscribe
again with the new UUID. Settings-only restores omit this field.
Fixtures¶
Capture with fixture: true to keep an Android emulator VM snapshot as a
reusable fixture, such as a state that took long to set up.
The snapshot then records what it depends on: the AVD, its system image and
hardware config, the emulator version, and its userdata image. A fixture must be an emulator VM snapshot: on a physical device, an iOS simulator, or with useVmSnapshot: false, the capture fails with fixture_requires_vm_snapshot and saves nothing.
AutoMobile re-reads the identity after saving; if it changed during the capture, the capture fails with fixture_invalidated and records nothing. When AUTOMOBILE_EMULATOR_ARGS redirects the userdata image with
-data, the fixture tracks that image.
Every restore of a fixture checks those inputs first, settings-only restores included. If any changed, AutoMobile refuses the restore, leaves the device as it was, and removes the fixture. It deletes the in-AVD snapshot then, or, if that fails, at the next capture on that emulator:
{
"success": false,
"code": "fixture_invalidated",
"snapshotName": "signed-in",
"retryable": false,
"reasons": ["userdata-wiped"]
}
| Reason | What changed |
|---|---|
system-image-changed |
The AVD’s system image package or its installed revision |
avd-config-changed |
The AVD’s hardware config |
emulator-version-changed |
The installed emulator |
userdata-wiped |
The userdata image was re-created, for example by -wipe-data |
avd-changed |
The AVD itself |
Capture the fixture again with fixture: true to replace it. Pass
fixture: true on restore to require a fixture:
| Restore of | Refused with |
|---|---|
| A snapshot captured without it | snapshot_not_a_fixture |
useVmSnapshot: false |
fixture_requires_vm_snapshot |
A fixture persists across sessions. VM retention (maxVmSnapshotsPerAvd,
maxVmArchiveSizeMb) neither evicts it nor counts it. It goes away only when it
is invalidated, when you delete it, or when deleteDevice destroys its AVD.
Deleting a snapshot¶
Delete any snapshot, fixture or not, by name:
{
"name": "deviceSnapshot",
"arguments": { "action": "delete", "snapshotName": "signed-in", "platform": "android" }
}
Run it on the snapshot’s own device, as for a restore; AutoMobile refuses a
snapshot of another device or AVD. The result has deleted: true once the snapshot and
its data are gone. A VM snapshot whose in-AVD payload cannot be deleted now
returns deleted: false with pendingReclaim: true. Delete it again, or
capture any snapshot on that emulator, to finish it.
Archive size, eviction, and reclaim¶
The archive resource automobile:deviceSnapshots/archive reports what the
snapshot archive costs and what still needs cleaning up:
| Field | Meaning |
|---|---|
totalSizeBytes |
Sum of every record whose size is known. |
unsizedCount |
Records whose payload could not be measured. They are not in totalSizeBytes, so a non-zero count means the archive is larger than the total says. |
pendingReclaimCount |
Records whose in-AVD VM snapshot still needs deleting because its emulator was offline. |
orphanedAvdSnapshots |
In-AVD snapshot directories with no record behind them. |
maxVmSnapshotsPerAvd |
Maximum VM snapshots retained for each Android AVD (default 3). |
maxVmArchiveSizeMb |
Optional additional per-AVD byte ceiling for VM snapshots; null means unlimited. |
maxArchiveSizeMb |
The byte budget for non-vm (app_data, adb, simctl) archive records (default 100 MB). |
An Android emulator VM snapshot lives inside the AVD at
~/.android/avd/<avd>.avd/snapshots/<name>/, not in the archive store. A vm
record’s size measures that directory, often a couple of gigabytes.
AutoMobile keeps up to maxVmSnapshotsPerAvd VM snapshots per AVD and evicts the
least recently accessed first. maxArchiveSizeMb does not apply to vm records.
You cannot set maxVmSnapshotsPerAvd, maxVmArchiveSizeMb, or maxArchiveSizeMb
through a CLI flag, environment variable, or MCP tool; the defaults apply.
Evicting a vm record deletes the in-AVD snapshot through the emulator console
(adb -s <serial> emu avd snapshot del <name>). When that emulator is not running,
AutoMobile keeps the record and flags it pendingReclaim. The next capture on
that AVD deletes the flagged snapshots.
Cleaning up orphaned in-AVD snapshots¶
orphanedAvdSnapshots skips the emulator’s default_boot quick-boot state.
AutoMobile never deletes orphans automatically, since one may be a snapshot
someone made by hand.
Each entry reports avdName, snapshotName, sizeBytes and directoryPath.
Use directoryPath for anything that touches the filesystem: it is the
directory the scan measured. Setting ANDROID_AVD_HOME, or an <avd>.ini file
pointing elsewhere, moves an AVD off the usual ~/.android/avd/<avd>.avd path.
To remove one yourself, with the AVD’s emulator running:
adb -s <serial> emu avd snapshot del <snapshot-name>
With the emulator stopped, delete the reported directory directly:
rm -rf "<directoryPath>"
Check what is there first with du -sh "<directoryPath>", or list every in-AVD
snapshot of one AVD with du -sh "$(dirname "<directoryPath>")"/*.