AndroidDevice
High-level class for managing Android devices.
android_device_manager.android_device.AndroidDevice
Attributes
name
property
The name of the managed AVD.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The name of the AVD. |
Functions
create(force=False)
Create the AVD if it does not exist.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
force
|
bool
|
If True, overwrite any existing AVD with the same name. |
False
|
Raises:
| Type | Description |
|---|---|
AVDCreationError
|
If the AVD cannot be created. |
delete()
start()
Start the emulator for the current AVD and wait for it to boot.
Raises:
| Type | Description |
|---|---|
EmulatorStartError
|
If the emulator fails to start. |
ADBError
|
If there is an error communicating with the device. |
TimeoutError
|
If the emulator does not boot within the allowed time. |
stop()
Stop the running emulator and release resources.
Raises:
| Type | Description |
|---|---|
Exception
|
If stopping the emulator fails. |
get_prop(key, timeout=10, check=True)
Retrieve a single Android system property from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str or AndroidProp
|
The name of the property, or an AndroidProp Enum. |
required |
timeout
|
int
|
Timeout in seconds for the adb command (default: 10). |
10
|
check
|
bool
|
Whether to raise an exception if the command fails (default: True). |
True
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The value of the requested property, or an empty string if not found. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not started or the ADB client is not initialized. |
ADBError
|
If there is a failure in communicating with the device. |
get_all_props(timeout=10)
Retrieve all Android system properties from the device as a dictionary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
timeout
|
int
|
Timeout in seconds for the adb command (default: 10). |
10
|
Returns:
| Type | Description |
|---|---|
dict[str, str]
|
dict[str, str]: A dictionary mapping property names to their values. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not started or the ADB client is not initialized. |
ADBError
|
If there is a failure in communicating with the device. |
root()
Restart the ADB daemon with root privileges.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the device is now running in root mode, False otherwise. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not started or the ADB client is not initialized. |
ADBError
|
If the operation fails. |
unroot()
Restart the ADB daemon without root privileges (back to user mode).
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the device is now running in unrooted mode, False otherwise. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not started or the ADB client is not initialized. |
ADBError
|
If the operation fails. |
is_root()
Check if the ADB daemon is currently running with root privileges.
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the device is running in root mode, False otherwise. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not started or the ADB client is not initialized. |
ADBError
|
If the operation fails. |
list_installed_packages()
List all installed package names on the device.
Returns:
| Type | Description |
|---|---|
list[str]
|
list[str]: A list of installed package names. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
is_package_installed(package_name)
Check if a given package is installed on the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package_name
|
str
|
The package name to check. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
bool |
bool
|
True if the package is installed, False otherwise. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
install_apk(apk_path, timeout=30)
Install an APK on the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
apk_path
|
str
|
The file path to the APK. |
required |
timeout
|
int
|
Timeout in seconds for the installation process (default: 30). |
30
|
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
install_multi_package(apk_paths, timeout=60)
Install multiple APKs on the device in a single transaction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
apk_paths
|
list[str]
|
A list of file paths to the APKs. |
required |
timeout
|
int
|
Timeout in seconds for the installation process (default: 60). |
60
|
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
uninstall_package(package_name, keep_data=False)
Uninstall a package from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
package_name
|
str
|
The name of the package to uninstall. |
required |
keep_data
|
bool
|
If True, application data and cache are retained (default: False). |
False
|
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running, the ADB client is not initialized, or the package is not installed. |
ADBError
|
If the command fails. |
push_file(local, remote)
Push a file from the local machine to the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
local
|
str or Path
|
Path to the local file to push. |
required |
remote
|
str
|
Destination path on the device. |
required |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
pull_file(remote, local)
Pull a file from the device to the local machine.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
remote
|
str
|
Path to the file on the device. |
required |
local
|
str or Path
|
Destination path on the local machine. |
required |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
pull_data_partition(dest_path='./data.tar')
Archive and pull the entire /data partition from the device.
The method switches to root mode, stops the Android runtime, archives the /data directory to a tar, pulls it to the local machine, removes the archive on the device, restarts Android, and returns to unrooted mode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
dest_path
|
str or Path
|
Local destination path for the pulled tarball (default: "./data.tar"). |
'./data.tar'
|
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If any command fails during the process. |
get_logcat(filter_spec=None)
Retrieve the current logcat output from the device.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
filter_spec
|
Optional[List[str]]
|
Optional list of logcat filters (e.g. ['*:E', 'ActivityManager:I']). |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The logcat output as a string. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
clear_logcat()
Clear the device's logcat logs.
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the device is not running or the ADB client is not initialized. |
ADBError
|
If the command fails. |
shell(args, timeout=30, check=True)
Execute a shell command on the device/emulator via ADB, with safety checks for forbidden commands.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
args
|
List[str]
|
The shell command as a list of arguments (e.g., ["ls", "/sdcard"]). |
required |
timeout
|
int
|
Timeout in seconds 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 containing stdout, stderr, and exit code. |
Raises:
| Type | Description |
|---|---|
AndroidDeviceError
|
If the command is forbidden (e.g., stop, reboot, poweroff). If the device is not running or the ADB client is not initialized. |
ADBError
|
If the shell command fails (when check is True). |
ADBTimeoutError
|
On timeout. |
__enter__()
Context manager entry: ensure device is created and started.
__exit__(exc_type, exc_val, exc_tb)
Context manager exit: stop the emulator and (optionally) delete the AVD.