Injecting Input and State — Drive the Device From the Shell
This skill covers the on-device shell surface a test/QA engineer drives over
to simulate user gestures, override the screen configuration, flip system settings, reset app state, and launch Activities. Transport (
, USB/TCP) lives in
../../architecture/understanding-adb-architecture/SKILL.md
; capturing artefacts after driving the device lives in
../../capture/capturing-screenshots-and-screenrecord/SKILL.md
.
When to use this skill
- The developer needs to script a user journey from CI without writing instrumentation: tap, swipe, type text, press hardware keys.
- A bug repro requires a specific screen size or density (, ) without recreating an emulator AVD.
- The test suite is flaky because animations are on; the developer wants the canonical hermetic preamble (
window_animation_scale = 0
etc.).
- The developer needs to clear app data between runs and is unsure whether is enough (it is not).
- A script uses
adb shell svc wifi disable
and silently does nothing on API 30+ — the modern cmd wifi set-wifi-enabled disabled
is the fix.
- The developer needs to launch a deep-link Activity with typed extras (, , ).
When NOT to use this skill
- The bytes need to leave the device (screenshots, logs, DB). Use
../../capture/capturing-screenshots-and-screenrecord/SKILL.md
, ../../observability/extracting-logs-with-logcat/SKILL.md
, ../../transfer/extracting-test-artifacts/SKILL.md
.
- Driving the device from inside an instrumentation test, not from the host. Use
../../../instrumentation/scenarios/launching-activities-with-activityscenario/SKILL.md
or UiAutomator.
- Installing or uninstalling APKs. Use
../../apps/installing-and-managing-apps/SKILL.md
.
- Connecting to the device in the first place. Use
../../devices/connecting-to-devices/SKILL.md
or ../../devices/connecting-over-wifi/SKILL.md
.
Prerequisites
- A reachable device or emulator ( returns ).
- Platform Tools 23+ on the host. Quoting through is double-shell (ssh-style) since Platform Tools 23 — load-bearing for any string with spaces (developer.android.com/tools/adb#shellcommands).
- For wrapper APIs and reliable shell exit codes: device API 24+ ( introduced API 24).
— synthesised user events
is the on-device wrapper around
InputManager.injectInputEvent()
. The full grammar:
input [<source>] <command> [<arg>...]
defaults per command (touchscreen for
/
, keyboard for
/
).
Tap, swipe, draganddrop
bash
adb shell input tap <x> <y>
adb shell input swipe <x1> <y1> <x2> <y2> [<duration_ms>]
adb shell input draganddrop <x1> <y1> <x2> <y2> [<duration_ms>]
adb shell input roll <dx> <dy> # rotary/trackball axes
adb shell input motionevent <DOWN|UP|MOVE|CANCEL> <x> <y>
defaults to ~300 ms when
is omitted. To synthesise a long-press, swipe in place for the long-press timeout:
input swipe <x> <y> <x> <y> 1000
.
differs from
in that it emits the drag-and-drop gesture sequence (DOWN → MOVE → UP) consumable by
, not the same event stream as
.
Text input — quoting trap
bash
adb shell input text "<string>"
Caveats (from developer.android.com/tools/adb):
- Spaces MUST be encoded as . types , then nothing.
- Shell metacharacters (, , , , , , , , , , backtick) MUST be escaped twice — once for the local shell, once for the device-side shell.
- Non-ASCII / Unicode is unreliable through . Use UiAutomator for those.
Key events
bash
adb shell input keyevent [--longpress|--doubletap] <KEYCODE> [<KEYCODE>...]
adb shell input keyevent <NUMERIC_CODE>
Test-relevant
(KeyEvent constants from frameworks/base; full table in research note A2):
| Mnemonic | Numeric | Notes |
|---|
| 3 | Press Home (does not always wake screen). |
| 4 | Back button. |
KEYCODE_DPAD_UP/DOWN/LEFT/RIGHT/CENTER
| 19-23 | TV / focus traversal. |
KEYCODE_VOLUME_UP/DOWN/MUTE
| 24/25/164 | |
| 26 | Toggles screen off/on. |
| 61 | |
| 66 | |
| 67 | Backspace. |
| 82 | |
| 187 | Recents button. |
| 224 | Wake without unlocking. |
| 223 | Force sleep. |
Wake + dismiss-keyguard for emulator with no lock:
bash
adb shell input keyevent KEYCODE_WAKEUP
adb shell input keyevent 82 # menu, dismiss the AOSP swipe-up
Source prefixes
maps to
. Use a source prefix when a screen has multiple input listeners or when targeting non-touch hardware:
| Source | Typical use |
|---|
| Default for , , . |
| External touchpads (Chromebook / Android tablet keyboard). |
| TV/focus traversal: input dpad keyevent KEYCODE_DPAD_DOWN
. |
| Default for , . |
| Mouse buttons + scroll. |
| Trackball roll. |
| / | Gamepad buttons / joystick axes. |
| Pressure-aware touch (S-Pen). |
— display size and density overrides
is the shell wrapper for
. The test-relevant subcommands:
bash
adb shell wm size # read current logical size
adb shell wm size 1080x1920 # override
adb shell wm size reset # restore device default
adb shell wm density # read current dpi
adb shell wm density 320 # override
adb shell wm density reset
adb shell wm dismiss-keyguard # insecure keyguard only
adb shell wm user-rotation [free|lock [<rotation>]] # 0,1,2,3 = 0/90/180/270
Use case — screen-size / density matrix without recreating the emulator:
bash
# Per configuration in the matrix
adb shell wm size 411x731
adb shell wm density 240
# … run tests …
adb shell wm size reset
adb shell wm density reset
Caveats:
- MUST call in / suite teardown — otherwise the device stays in the modified configuration after the run, breaking later runs and any human user.
- / trigger a configuration change that recreates the foreground Activity. Treat them as between-test knobs, not mid-test.
- / are equivalent legacy spellings; is preferred.
— hermetic test state
bash
adb shell settings [--user <id>] get <namespace> <key>
adb shell settings [--user <id>] put <namespace> <key> <value> [<tag>] [default]
adb shell settings [--user <id>] delete <namespace> <key>
adb shell settings [--user <id>] reset <namespace> [<package>] [untrusted_defaults|untrusted_clear|trusted_defaults]
adb shell settings [--user <id>] list <namespace>
The hermetic preamble — animation knobs
Set all three to
for stable instrumented and screenshot tests:
bash
adb shell settings put global window_animation_scale 0
adb shell settings put global transition_animation_scale 0
adb shell settings put global animator_duration_scale 0
Or via Gradle:
testOptions.animationsDisabled = true
.
Other test-relevant keys
| Namespace | Key | Purpose |
|---|
| | Float (e.g. , ); type-scale tests. |
| | to enable a11y; pair with enabled_accessibility_services
. |
| enabled_accessibility_services
| CSV for a11y tests. |
| | Force a known IME. |
| show_ime_with_hard_keyboard
| to keep IME visible on emulators. |
| | Stabilise long-press tests. |
| | Pair with am broadcast android.intent.action.AIRPLANE_MODE
. |
| | E.g. to hide system bars. |
App state — vs
| Command | Kills processes? | Clears data/cache/prefs? | Resets runtime permissions? |
|---|
| Yes | No | No |
| Yes (implicitly) | Yes | Yes |
cmd activity stop-app <pkg>
| Yes (modern, API 28+) | No | No |
For a hermetic between-test reset, use
. For "kill the process so the next launch is cold",
is enough. See
../../apps/installing-and-managing-apps/SKILL.md
for the full
surface.
Launching Activities —
bash
# Most reliable for tests: explicit component.
adb shell am start -n com.example.app/.MainActivity
# Force-stop first, then launch (clean cold start).
adb shell am start -S -W -n com.example.app/.MainActivity
# Launch by action + URI (default handler for https://).
adb shell am start -a android.intent.action.VIEW -d 'https://example.com'
# Pass typed extras.
adb shell am start -n com.example.app/.MainActivity \
--es screen "settings" --ez debug true --ei count 42
# Return to launcher between tests.
adb shell am start -a android.intent.action.MAIN -c android.intent.category.HOME
Intent specifier flags (abridged from developer.android.com/tools/adb#IntentSpec):
| Token | Effect |
|---|
| Intent action (e.g. android.intent.action.VIEW
). |
| Data URI. |
| MIME type. |
| Category. |
| Explicit component (). |
| Hex value. |
| `--es | -e key value` |
| Boolean extra. |
| Int extra. |
| Long extra. |
| Float extra. |
| URI extra. |
| ComponentName extra. |
--eia/--ela/--efa key v[,v...]
| Array extras. |
| etc. | Map to . |
| Force-stop the target before starting. |
| Wait for launch to complete. |
— the modern wrapper
is a generic wrapper that calls into a binder service's
. Available since API 24. To list services:
(or
). Test-relevant entry points:
| Invocation | Effect |
|---|
cmd activity stop-app <pkg>
| Modern equivalent of . |
| Same as . |
cmd package install -r -t -g <path>
| equivalent. |
cmd package compile -m speed -f <pkg>
| Force AOT compilation. |
| `cmd appops set <pkg> <op> allow | deny |
cmd jobscheduler run -f <pkg> <jobId>
| Force a JobService to run now. |
| `cmd uimode night yes | no |
cmd locale set-app-locales <pkg> --locales en-US
| Per-app locales (Android 13+). |
cmd statusbar expand-notifications
/ | Expand/collapse the shade. |
| `cmd wifi set-wifi-enabled enabled | disabled` |
| `cmd connectivity airplane-mode enable | disable` |
| Reset device to a hermetic test-harness state (Android 10+). |
deprecation on API 30+
,
,
are
no-ops on API 30+ unless invoked from a privileged shell (corpus §I.10). The preferred replacements are the
wrappers above.
Patterns
Pattern: WRONG — on API 30+
bash
# WRONG
adb shell svc wifi disable
# WRONG because: silently no-ops on API 30+ since the svc CLI was demoted from a privileged
# helper to an ordinary shell command. Exit code 0, Wi-Fi still on. The script proceeds
# under a wrong assumption — exactly the worst kind of failure mode.
bash
# RIGHT
adb shell cmd wifi set-wifi-enabled disabled
adb shell cmd wifi status # verify
Pattern: WRONG — for a between-test reset
bash
# WRONG
adb shell am force-stop com.example.app
./run-next-test.sh
# WRONG because: am force-stop kills the process but leaves shared prefs, databases, the
# image cache, and granted runtime permissions intact. The "next test" inherits state
# from the previous run.
bash
# RIGHT
adb shell pm clear com.example.app
adb shell pm clear com.example.app.test # also reset test process state
./run-next-test.sh
(Test Orchestrator with
is the equivalent inside Gradle — see
../../tests/running-instrumented-tests-via-adb/SKILL.md
.)
Pattern: WRONG —
bash
# WRONG
adb shell input text "hello world"
# WRONG because: spaces in `input text` MUST be encoded as %s. The above types only "hello".
bash
# RIGHT
adb shell input text 'hello%sworld'
Pattern: hermetic preamble + Activity launch
bash
adb shell settings put global window_animation_scale 0
adb shell settings put global transition_animation_scale 0
adb shell settings put global animator_duration_scale 0
adb shell pm clear com.example.app
adb shell am start -S -W -n com.example.app/.MainActivity
force-stops first;
blocks until the launch completes.
Pattern: TV / focus navigation via dpad
bash
adb shell input dpad keyevent KEYCODE_DPAD_DOWN
adb shell input dpad keyevent KEYCODE_DPAD_DOWN
adb shell input dpad keyevent KEYCODE_DPAD_CENTER
Source-prefixing
ensures the events route to TV-style focus handlers, not the touchscreen pipeline.
Mandatory rules
- MUST use
cmd wifi set-wifi-enabled
/ cmd connectivity airplane-mode
/ cmd bluetooth_manager enable
on API 30+. MUST NOT rely on / / — they no-op silently on modern releases.
- MUST use (not ) when the goal is a hermetic between-test reset. only kills processes; data is untouched.
- MUST encode spaces in as ; MUST double-shell quote (ssh-style) any string with shell metacharacters. Platform Tools 23+ (developer.android.com/tools/adb#shellcommands).
- MUST call and in suite teardown when the suite overrode them. A leaked override breaks every subsequent run on that device.
- MUST set the three animation scales to (or use
testOptions.animationsDisabled = true
in Gradle) before any UI-asserting test run.
- MUST NOT use between calls to "let the UI catch up". Inside an instrumentation test, use Compose's idle synchronisation (
../../../compose/synchronization/synchronizing-with-idle/SKILL.md
); from a host script, use to block on Activity launch and adb shell wait-for-device
between reboots.
- MUST NOT assume returns a meaningful exit code without . See
../../tests/running-instrumented-tests-via-adb/SKILL.md
and ../../automation/scripting-adb-for-ci/SKILL.md
.
- PREFERRED:
am start -S -W -n pkg/.Activity
for cold-start launches in tests — resets, blocks until ready.
Verification
References
- developer.android.com/tools/adb — , , , , , intent specs (https://developer.android.com/tools/adb).
- developer.android.com/tools/adb#shellcommands — quoting through since Platform Tools 23.
- developer.android.com/reference/android/view/KeyEvent — constants table.
- developer.android.com/training/testing/instrumented-tests/stability — the canonical animation-scale-zero recipe.
- developer.android.com/studio/test/advanced-test-setup#use-gradle-managed-devices —
testOptions.animationsDisabled
.
- Research note
tasks/research/A2-adb-shell-commands.md
— full / / / / / / tables and verbatim quotes.
- Sibling skill:
../../architecture/understanding-adb-architecture/SKILL.md
— three-piece architecture, server, daemon.
- Sibling skill:
../../devices/connecting-to-devices/SKILL.md
— states, .
- Sibling skill:
../../devices/connecting-over-wifi/SKILL.md
— / .
- Sibling skill:
../../apps/installing-and-managing-apps/SKILL.md
— full / / surface.
- Sibling skill:
../../tests/running-instrumented-tests-via-adb/SKILL.md
— .
- Sibling skill:
../../capture/capturing-screenshots-and-screenrecord/SKILL.md
— capturing artefacts after driving the device.
- Sibling skill:
../../observability/extracting-logs-with-logcat/SKILL.md
— reading device logs.
- Sibling skill:
../../transfer/extracting-test-artifacts/SKILL.md
— / / .
- Sibling skill:
../../automation/scripting-adb-for-ci/SKILL.md
— bash idioms, retries, port forwarding.
- Cross-set:
../../../instrumentation/scenarios/launching-activities-with-activityscenario/SKILL.md
— launching from inside an instrumentation test.
- Cross-set:
../../../fundamentals/strategies/applying-testing-strategies/SKILL.md
— when to drive via vs instrumentation.