Device condition fixtures¶
setDeviceState can put an Android device into a fault or root state, or set an iOS Simulator’s status bar, privacy decisions or location, for a test, then restore it. Send a deviceCondition object as the call’s only field; it cannot be combined with other setDeviceState fields.
{
"deviceCondition": {
"faults": { "revokePermission": { "package": "com.example.app", "permission": "CAMERA" } }
}
}
Enabling it¶
deviceCondition is behind the device-condition feature flag, which is off by default. While it is off, every deviceCondition call fails with:
setDeviceState deviceCondition is behind the 'device-condition' feature flag, which is disabled. Enable it with `auto-mobile --daemon set-feature-flag device-condition true` or in the IDE plugin under Settings > AutoMobile > Feature Flags, then retry the call.
Turn it on from a shell with:
auto-mobile --daemon set-feature-flag device-condition true
or in the AutoMobile IDE plugin under Settings > AutoMobile > Feature Flags. The flag applies to the whole host, not one session, and stays set across daemon restarts. Pass false to turn it off again.
Exporting key attestation¶
On Android, call setDeviceState with { "deviceCondition": { "exportAttestation": true } } to export a temporary key’s public certificate chain for a test backend. Send this alone, without conditions, reset or a lease; no session is required. The temporary key is deleted before the response is sent. If the image cannot generate attestation, the call fails; use an image supporting key attestation. If the installed automation service predates this action (it requires CtrlProxy 0.0.90 or newer), the call fails with an error naming that version; install CtrlProxy 0.0.90 or newer.
The attestation result contains certificateChainBase64 (base64 DER, leaf first and root last) and rootCertificateBase64. Its fields hold numeric attestationSecurityLevel and keymasterSecurityLevel, deviceLocked, verifiedBootState, and attestationApplicationId (raw base64, package names, decimal version strings and base64 signing-certificate digests). Missing optional fields are null. These are the certificate’s reported fields, not a passing-integrity verdict or signature validation. The application ID describes the automation service that generated the key, not your app. Use the exported root only in your test backend’s trust configuration; your backend still validates the app’s own attestation chain and policy.
Conditions¶
Set a condition by passing its value. Pass "unset" to clear it, or { "reset": true } to restore everything applied on the device.
| Field | What it does | Restored on reset |
|---|---|---|
rootState: "rooted-detectable" |
Makes root-detection checks trip (non-Play emulator image with a writable /system) |
Yes |
faults.battery |
unplug, low (15%) or full |
Yes |
faults.lowPower |
Battery saver on | Yes, to its prior value |
faults.doze |
Forces deep Doze | Yes |
faults.thermal |
throttling or critical thermal status |
Yes |
faults.dontKeepActivities |
Developer option “Don’t keep activities” on | Yes, to its prior value |
faults.memoryPressure: "on" |
Holds more than MemAvailable (up to 16384 MiB) to exhaust swap and trigger lmkd to kill background apps; unsupported if no kill follows. Uses a local build or AUTOMOBILE_LMK_PRESSURE_DIR, otherwise downloads the checksum-verified binary for the device ABI from the release. |
Yes, stops the payload and removes its files; killed apps stay stopped |
faults.storage |
low (about 128 MiB free) or full (about 8 MiB free) |
Yes |
faults.readOnlyFilesystem: "on" |
Makes shared storage /sdcard read-only for every app; writes fail with “Read-only file system” (EROFS). Rootable emulators only |
Yes |
faults.corruptAppFile |
Damages one file in a debuggable app’s data directory | Yes, from a saved copy |
faults.revokePermission |
Revokes one runtime permission | Yes, re-granted |
faults.lockScreen |
Sets an AutoMobile test PIN or removes the PIN; removal invalidates lock-screen-bound keys. unset restores no lock screen |
Yes, restores no lock screen |
faults.biometricEnrollment |
Emulators only: add enrolls one more fingerprint, which invalidates keys created with setInvalidatedByBiometricEnrollment(true); none removes every fingerprint |
Yes, restores no lock screen and no fingerprints |
faults.disablePackage |
Disables an app for the current user | Yes, re-enabled |
faults.clockSkew |
Moves the device clock offsetSeconds from real time, with automatic time off |
Yes, to real time and the original automatic-time setting |
faults.killApp |
Ends an app’s process once (background or forceStop) |
No: one-shot |
faults.trimMemory |
Sends a running app one onTrimMemory level; foreground needs RUNNING_* (Android refuses HIDDEN, BACKGROUND, MODERATE, COMPLETE) |
No: one-shot |
faults.clearPackageData |
Clears an app’s data | No: one-shot, cannot be undone |
vehicle.motion, vehicle.nightMode |
Automotive vehicle state; see Android Automotive OS | Yes |
statusBar |
iOS Simulator: overrides time, batteryLevel, batteryState, cellularBars, wifiBars, dataNetwork and operatorName (at least one) |
Yes, every override cleared |
privacy |
iOS Simulator: grants or revokes one privacy service for an app ({ appId, service, action }) |
Yes, to the app’s earlier decision |
location |
iOS Simulator: simulates the device location ({ latitude, longitude }) |
Yes, simulated location cleared |
rootState needs a non-Play image booted with -writable-system, which keeps /system writable. Without it, apply returns unsupported with guidance to boot with -writable-system. After the daemon stops with the fixture applied, the next unset or reset on the device removes the planted files and restores SELinux.
faults.biometricEnrollment drives the emulator’s Settings enrollment screens and touches its virtual sensor with adb emu finger touch. It needs an emulator whose console accepts finger commands and whose system language is English, and AutoMobile refuses it on a physical device.
Settings only enrolls a fingerprint behind a lock screen. The first add needs a device with no lock screen and sets the AutoMobile test PIN (1234); each later add enrolls another fingerprint, up to five. Android deletes fingerprints with the lock-screen credential, so none, unset and reset all clear the test PIN. That leaves no lock screen and no fingerprints, and Android deletes lock-screen-bound keys too. Do not combine it with faults.lockScreen.
To invalidate an enrollment-bound key: add once, have the app create its key, then add again.
faults.memoryPressure ends by itself 30 minutes after the payload becomes ready, even if the daemon dies.
A condition the device cannot apply comes back unsupported with a detail reason, and the call reports success: false. The call’s other changes still apply.
iOS Simulator¶
On an iOS Simulator, statusBar, privacy and location apply and restore like the Android conditions. On Android or a physical iOS device they return unsupported.
privacy.service is one of calendar, contacts-limited, contacts, location, location-always, photos-add, photos, media-library, microphone, motion, reminders or siri. Reset puts back the app’s earlier decision for that service: granted, denied, or not yet asked. These pairs change together, and reset restores both services in a pair: photos and photos-add, location and location-always, contacts and contacts-limited. If the app already has the requested decision, the change is unchanged. If its earlier decision cannot be restored, such as limited Photos access, the request is refused and nothing changes; reset the app’s privacy settings first.
Every other condition returns unsupported on an iOS Simulator, with the reason. rootState and integrityState need a bootloader, verified boot or a jailbroken device; the Simulator has none. The faults and vehicle conditions need Android system services. For faults.battery, use statusBar to change the displayed battery; for faults.revokePermission, use privacy with action: "revoke".
Compound faults¶
Some faults cause a second fault. Plan your test for both:
revokePermissionrestarts the app. Android kills an app’s process when one of its permissions is revoked, so the app is also restarted.corruptAppFileforce-stops the app before it damages the file.clearPackageDatakills the app’s process as well as deleting its data.clockSkewrestarts adbd. It needsadb root, so it works only on rootable emulators, and the device’s adb connection drops briefly while adbd restarts.
Restore¶
Every restorable condition is undone, newest first, when any of these happens:
- the session that applied it is released or rebound;
- its lease expires:
expiresInSeconds(1 to 86,400) restores everything after that many seconds unless a laterdeviceConditioncall renews it. Leases need a session; - you call
{ "deviceCondition": { "reset": true } }.
Conditions belong to the device, not to the caller that set them. When two sessions, or a session and a call without one, set the same condition on one device, they act on one shared device state. Only the caller that applied it first can undo it: its release or reset clears the condition for both. The second caller’s request reports unchanged, and its release or reset leaves the condition in place. Give each condition-setting run its own device.
After each reset, AutoMobile reads the device back to check the condition is gone. One-shot faults (killApp, trimMemory, clearPackageData) have nothing to restore, and "unset" on them does nothing.
Result¶
The result lists each requested change with its status (applied, cleared, unchanged or unsupported) and the keys still active on the device. Calls that reset conditions also include restore: the keys restored, any failures with the key and the reason, and verifiedClean. When verifiedClean is false, the daemon log names each condition left unrestored. That condition stays registered, so the next release or reset tries again.