Instrumentation Tests

Running an Android instrumentation test runner on a connected device (adb shell am instrument -w -r). run_instrumentation always waits for the run to finish and requests raw output, then parses the INSTRUMENTATION_STATUS / INSTRUMENTATION_STATUS_CODE / ..._RESULT / ..._CODE markers into pass/fail/error counts, the final result code, and the runner's summary stream. Typed -e name value runner arguments, --user scope, --no-window-animation, and a bounded timeout_s are supported; a free-form argument string is not. Test failures are returned as data — only a failure to start the runner raises (INSTRUMENTATION_FAILED).

run_instrumentation

Run an instrumentation test runner: adb shell am instrument -w -r.

Always runs with -w (wait for completion — required for test runners) and -r (raw output), then parses the INSTRUMENTATION_STATUS/RESULT/CODE marker stream into pass/fail/error counts and the runner's summary. Categorized write because a test run executes arbitrary app code on the device. Test failures are a normal result returned as data — only a failure to start the runner is an error.

Parameters:

Name	Type	Description	Default
serial	str	The target device's adb serial (see list_connected_devices).	required
component	str	The instrumentation to run, as "/" (e.g. "com.example.test/androidx.test.runner.AndroidJUnitRunner"), or just "" when it declares only one.	required
args	dict[str, str] | None	Runner arguments passed as -e <name> <value> pairs, e.g. {"class": "com.example.FooTest#testBar"} or {"package": "com.example.feature"}. Omit for none.	None
user_id	int | None	Run the instrumentation as this Android user (--user). Omit for the current user.	None
no_window_animation	bool	Pass --no-window-animation to disable window animations during the run.	False
timeout_s	float	How long to wait for the run to finish, 1-600 seconds (default 120). A run exceeding this raises TIMEOUT.	120.0

Returns:

Type	Description
InstrumentationRun	The serial and component; completed (false if the run was cut short); result_code (the final INSTRUMENTATION_CODE); tests_total (declared numtests when reported); tests_passed / tests_failed / tests_errored counts; result_stream (the runner's human-readable summary); and raw (the capped marker output).

Error handling

A blank component, negative user_id, or out-of-range timeout_s raises INVALID_ARGUMENT before anything runs. An unknown serial or unresponsive adb binary raises DEVICE_NOT_FOUND/ADB_UNAVAILABLE. A component whose test package/runner isn't installed raises INSTRUMENTATION_FAILED (am exits 0 for this, so it's detected from the output). A permission rejection raises PERMISSION_DENIED; any other non-zero exit raises BACKEND_ERROR; a run that exceeds timeout_s raises TIMEOUT.

Example

Called with serial="emulator-5554", component="com.example.test/androidx.test.runner.AndroidJUnitRunner", args={"class": "com.example.FooTest"}. A typical response:

{
  "status": "success",
  "message": "instrumentation com.example.test/androidx.test.runner.AndroidJUnitRunner on emulator-5554: 2 passed, 0 failed, 0 errored (code -1).",
  "data": {
    "serial": "emulator-5554",
    "component": "com.example.test/androidx.test.runner.AndroidJUnitRunner",
    "completed": true,
    "result_code": -1,
    "tests_total": 2,
    "tests_passed": 2,
    "tests_failed": 0,
    "tests_errored": 0,
    "result_stream": "OK (2 tests)",
    "raw": "INSTRUMENTATION_STATUS: numtests=2\n..."
  },
  "error": null
}