ADB Module
Interact with Android Debug Bridge (ADB).
android_device_manager.adb.client
Classes
AdbClient
A client for interacting with an Android emulator/device via the Android Debug Bridge (ADB).
Functions
__init__(emulator_port, android_sdk=None)
Initialize the AdbClient.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
emulator_port
|
int
|
The TCP port number of the emulator (e.g., 5554). |
required |
android_sdk
|
AndroidSDK
|
The Android SDK abstraction providing the adb path. |
None
|
get_all_props(timeout=10)
Get all Android system properties as a dictionary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeout
|
int
|
Timeout in seconds. |
10
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
dict[str, str]: All system properties as {key: value} |
Raises:
| Type | Description |
|---|---|
ADBError
|
On failure. |
get_prop(key, timeout=10, check=True)
Get a single Android system property via adb.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str or AndroidProp
|
The name of the property, or an AndroidProp Enum. |
required |
timeout
|
int
|
Timeout in seconds. |
10
|
check
|
bool
|
Raise if the command fails. |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Value of the property, or '' if not found. |
Raises:
| Type | Description |
|---|---|
ADBError
|
If the adb command fails. |
wait_for_boot(timeout=120)
Wait for the emulator to fully boot (until 'sys.boot_completed' is set).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeout
|
int
|
Maximum time to wait in seconds (default: 120). |
120
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the device booted successfully before the timeout. |
Raises:
| Type | Description |
|---|---|
TimeoutError
|
If the device did not boot in the specified time. |
kill_emulator()
Kill (terminate) the emulator instance via ADB.
Raises:
| Type | Description |
|---|---|
ADBError
|
If the emulator could not be killed. |
root(timeout=10, check=True)
Restart adbd with root permissions, if possible.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeout
|
int
|
Timeout for the command (default: 10s) |
10
|
check
|
bool
|
Raise if the command fails. |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if adbd is now running as root, False otherwise. |
Raises:
| Type | Description |
|---|---|
ADBError
|
On failure to restart adbd. |
is_root(timeout=10)
Check if adbd is running as root on the device.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if running as root, False otherwise. |
list_installed_packages()
List installed package names on the device. Returns: list[str]: Package names. Raises: ADBError: On failure.
install_apk(apk_path, timeout=60)
Install an APK file on the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
apk_path
|
str
|
Path to the APK file on the host. |
required |
timeout
|
int
|
Timeout in seconds for the installation. |
60
|
Raises:
| Type | Description |
|---|---|
ADBError
|
If the installation fails. |
install_multi_package(apk_paths, timeout=120)
Install multiple APKs in a single transaction using 'adb install-multi-package'.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
apk_paths
|
list[str]
|
List of APK file paths on the host. |
required |
timeout
|
int
|
Timeout in seconds for the installation. |
120
|
Raises:
| Type | Description |
|---|---|
ADBError
|
If the installation fails. |
uninstall_package(package_name, keep_data=False, timeout=60)
Uninstall a package from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package_name
|
str
|
The full package name to uninstall. |
required |
keep_data
|
bool
|
If True, keep app data and cache (default: False). |
False
|
timeout
|
int
|
Timeout in seconds. |
60
|
Raises:
| Type | Description |
|---|---|
ADBError
|
If the uninstallation fails. |
push_file(local, remote, timeout=60, check=True)
Push a file from the local host to the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
local
|
str | Path
|
Path to the local file. |
required |
remote
|
str
|
Destination path on the device (e.g., /sdcard/file.txt). |
required |
timeout
|
int
|
Timeout in seconds. |
60
|
check
|
bool
|
Raise exception on failure. |
True
|
Raises:
| Type | Description |
|---|---|
ADBError
|
If the command fails. |
ADBTimeoutError
|
On timeout. |
pull_file(remote, local, timeout=60, check=True)
Pull a file from the device to the local host.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
remote
|
str
|
Path to the file on the device. |
required |
local
|
str | Path
|
Destination path on the host. |
required |
timeout
|
int
|
Timeout in seconds. |
60
|
check
|
bool
|
Raise exception on failure. |
True
|
Raises:
| Type | Description |
|---|---|
ADBError
|
If the command fails. |
ADBTimeoutError
|
On timeout. |
get_logcat(filter_spec=None, timeout=30, check=True)
Retrieve logcat output from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filter_spec
|
Optional[List[str]]
|
List of filter spec strings, e.g., ['*:E', 'ActivityManager:I'] |
None
|
timeout
|
int
|
Timeout for the command. |
30
|
check
|
bool
|
Raise on non-zero exit code. |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
Logcat output (stdout). |
Raises:
| Type | Description |
|---|---|
ADBError
|
If adb command fails. |
ADBTimeoutError
|
On timeout. |
clear_logcat(timeout=10, check=True)
Clear the device logcat buffer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeout
|
int
|
Timeout for the command (default: 10 seconds). |
10
|
check
|
bool
|
If True, raise if the command fails. |
True
|
Raises:
| Type | Description |
|---|---|
ADBError
|
If the command fails. |
AVDTimeoutError
|
On timeout. |
shell(cmd, timeout=30, check=True)
Execute a shell command on the device/emulator via ADB.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cmd
|
list[str]
|
The shell command as a list of arguments. Example: ["ls", "/sdcard"] |
required |
timeout
|
int
|
Timeout for the command (default: 30). |
30
|
check
|
bool
|
If True, raise an exception for non-zero exit code. |
True
|
Returns:
| Type | Description |
|---|---|
CompletedProcess
|
subprocess.CompletedProcess: The result object (stdout, stderr, etc.). |
Raises:
| Type | Description |
|---|---|
ADBError
|
If the command fails (and check=True). |
ADBTimeoutError
|
On timeout. |
android_device_manager.adb.exceptions
Classes
ADBTimeoutError
Bases: AndroidDeviceManagerError
Raised when a timeout occurs during an ADB operation.
ADBError
Bases: AndroidDeviceManagerError
Raised for any error encountered while running an ADB (Android Debug Bridge) command.
Attributes:
| Name | Type | Description |
|---|---|---|
return_code |
Optional[int]
|
The process return code, if available. |
cmd |
Optional[Any]
|
The command that was executed. |
stdout |
Optional[str]
|
The standard output from the failed command. |
stderr |
Optional[str]
|
The standard error from the failed command. |
serial |
Optional[str]
|
The emulator/device serial associated with the error, if relevant. |
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
message
|
str
|
A descriptive error message. |
required |
return_code
|
Optional[int]
|
The process return code. |
None
|
cmd
|
Optional[Any]
|
The command executed (as a list or string). |
None
|
stdout
|
Optional[str]
|
Output from stdout. |
None
|
stderr
|
Optional[str]
|
Output from stderr. |
None
|
serial
|
Optional[str]
|
The serial of the target device. |
None
|