mozdevice — Interact with Android or B2G devices

Mozdevice provides several interfaces to interact with an Android or B2G device such as a phone, tablet, or emulator. It allows you to push files to these types of devices, launch processes, and more. There are currently two available interfaces:

ADB Interface

The following classes provide a basic interface to interact with the Android Debug Tool (adb) and Android-based devices. It has replaced the now defunct DeviceManager and DeviceManagerADB classes.

ADBCommand

class mozdevice.ADBCommand(adb='adb', adb_host=None, adb_port=None, logger_name='adb', timeout=300, verbose=False, require_root=True)

ADBCommand provides a basic interface to adb commands which is used to provide the ‘command’ methods for the classes ADBHost and ADBDevice.

ADBCommand should only be used as the base class for other classes and should not be instantiated directly. To enforce this restriction calling ADBCommand’s constructor will raise a NonImplementedError exception.

from mozdevice import ADBCommand

try:
    adbcommand = ADBCommand()
except NotImplementedError:
    print "ADBCommand can not be instantiated."
ADBCommand.command(self, cmds, timeout=None)

Executes an adb command on the host.

Parameters:
  • cmds (list) – The command and its arguments to be executed.
  • device_serial (str or None) – The device’s serial number if the adb command is to be executed against a specific device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBCommand constructor is used.
Returns:

mozdevice.ADBProcess

command() provides a low level interface for executing commands on the host via adb.

command() executes on the host in such a fashion that stdout of the adb process is a file handle on the host and the exit code is available as the exit code of the adb process.

The caller provides a list containing commands, as well as a timeout period in seconds.

A subprocess is spawned to execute adb with stdout and stderr directed to a temporary file. If the process takes longer than the specified timeout, the process is terminated.

It is the caller’s responsibilty to clean up by closing the stdout temporary file.

ADBCommand.command_output(self, cmds, timeout=None)

Executes an adb command on the host returning stdout.

Parameters:
  • cmds (list) – The command and its arguments to be executed.
  • device_serial (str or None) – The device’s serial number if the adb command is to be executed against a specific device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBCommand constructor is used.
Returns:

string - content of stdout.

Raises:
  • ADBTimeoutError
  • ADBError

ADBHost

class mozdevice.ADBHost(adb='adb', adb_host=None, adb_port=None, logger_name='adb', timeout=300, verbose=False)

ADBHost provides a basic interface to adb host commands which do not target a specific device.

from mozdevice import ADBHost

adbhost = ADBHost()
adbhost.start_server()
ADBHost.command(self, cmds, timeout=None)

Executes an adb command on the host.

Parameters:
  • cmds (list) – The command and its arguments to be executed.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBHost constructor is used.
Returns:

mozdevice.ADBProcess

command() provides a low level interface for executing commands on the host via adb.

command() executes on the host in such a fashion that stdout of the adb process is a file handle on the host and the exit code is available as the exit code of the adb process.

The caller provides a list containing commands, as well as a timeout period in seconds.

A subprocess is spawned to execute adb with stdout and stderr directed to a temporary file. If the process takes longer than the specified timeout, the process is terminated.

It is the caller’s responsibilty to clean up by closing the stdout temporary file.

ADBHost.command_output(self, cmds, timeout=None)

Executes an adb command on the host returning stdout.

Parameters:
  • cmds (list) – The command and its arguments to be executed.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBHost constructor is used.
Returns:

string - content of stdout.

Raises:
  • ADBTimeoutError
  • ADBError
ADBHost.start_server(self, timeout=None)

Starts the adb server.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBHost constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError

Attempting to use start_server with any adb_host value other than None will fail with an ADBError exception.

You will need to start the server on the remote host via the command:

adb -a fork-server server

If you wish the remote adb server to restart automatically, you can enclose the command in a loop as in:

while true; do
  adb -a fork-server server
done
ADBHost.kill_server(self, timeout=None)

Kills the adb server.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBHost constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError
ADBHost.devices(self, timeout=None)

Executes adb devices -l and returns a list of objects describing attached devices.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBHost constructor is used.

Returns:

an object contain

Raises:
  • ADBTimeoutError
  • ADBListDevicesError
  • ADBError

The output of adb devices -l

$ adb devices -l
List of devices attached
b313b945               device usb:1-7 product:d2vzw model:SCH_I535 device:d2vzw

is parsed and placed into an object as in

[{‘device_serial’: ‘b313b945’, ‘state’: ‘device’, ‘product’: ‘d2vzw’,
‘usb’: ‘1-7’, ‘device’: ‘d2vzw’, ‘model’: ‘SCH_I535’ }]

ADBDevice

class mozdevice.ADBDevice(device=None, adb='adb', adb_host=None, adb_port=None, test_root='', logger_name='adb', timeout=300, verbose=False, device_ready_retry_wait=20, device_ready_retry_attempts=3)

ADBDevice is an abstract base class which provides methods which can be used to interact with the associated Android or B2G based device. It must be used via one of the concrete implementations in ADBAndroid or ADBB2G.

Host Command methods

ADBDevice.command(self, cmds, timeout=None)

Executes an adb command on the host against the device.

Parameters:
  • cmds (list) – The command and its arguments to be executed.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Returns:

mozdevice.ADBProcess

command() provides a low level interface for executing commands for a specific device on the host via adb.

command() executes on the host in such a fashion that stdout of the adb process are file handles on the host and the exit code is available as the exit code of the adb process.

For executing shell commands on the device, use ADBDevice.shell(). The caller provides a list containing commands, as well as a timeout period in seconds.

A subprocess is spawned to execute adb for the device with stdout and stderr directed to a temporary file. If the process takes longer than the specified timeout, the process is terminated.

It is the caller’s responsibilty to clean up by closing the stdout temporary file.

ADBDevice.command_output(self, cmds, timeout=None)

Executes an adb command on the host against the device returning stdout.

Parameters:
  • cmds (list) – The command and its arguments to be executed.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Returns:

string - content of stdout.

Raises:
  • ADBTimeoutError
  • ADBError

Device Shell methods

ADBDevice.shell(self, cmd, env=None, cwd=None, timeout=None, root=False)

Executes a shell command on the device.

Parameters:
  • cmd (str) – The command to be executed.
  • env (dict or None) – Contains the environment variables and their values.
  • cwd (str or None) – The directory from which to execute.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
  • stdout_callback – Function called for each line of output.
Returns:

mozdevice.ADBProcess

Raises:

ADBRootError

shell() provides a low level interface for executing commands on the device via adb shell.

shell() executes on the host in such as fashion that stdout contains the stdout and stderr of the host abd process combined with the stdout and stderr of the shell command on the device. The exit code of shell() is the exit code of the adb command if it was non-zero or the extracted exit code from the output of the shell command executed on the device.

The caller provides a flag indicating if the command is to be executed as root, a string for any requested working directory, a hash defining the environment, a string containing shell commands, as well as a timeout period in seconds.

The command line to be executed is created to set the current directory, set the required environment variables, optionally execute the command using su and to output the return code of the command to stdout. The command list is created as a command sequence separated by && which will terminate the command sequence on the first command which returns a non-zero exit code.

A subprocess is spawned to execute adb shell for the device with stdout and stderr directed to a temporary file. If the process takes longer than the specified timeout, the process is terminated. The return code is extracted from the stdout and is then removed from the file.

It is the caller’s responsibilty to clean up by closing the stdout temporary files.

ADBDevice.shell_bool(self, cmd, env=None, cwd=None, timeout=None, root=False)

Executes a shell command on the device returning True on success and False on failure.

Parameters:
  • cmd (str) – The command to be executed.
  • env (dict or None) – Contains the environment variables and their values.
  • cwd (str or None) – The directory from which to execute.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Returns:

boolean

Raises:
  • ADBTimeoutError
  • ADBRootError
ADBDevice.shell_output(self, cmd, env=None, cwd=None, timeout=None, root=False)

Executes an adb shell on the device returning stdout.

Parameters:
  • cmd (str) – The command to be executed.
  • env (dict or None) – Contains the environment variables and their values.
  • cwd (str or None) – The directory from which to execute.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Returns:

string - content of stdout.

Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError

Informational methods

ADBDevice.clear_logcat(timeout=None, buffers=[])

Clears logcat via adb logcat -c.

Parameters:
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • buffers (list) – Log buffers to clear. Valid buffers are “radio”, “events”, and “main”. Defaults to “main”.
Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.get_battery_percentage(timeout=None)

Abstract class that returns the battery charge as a percentage.

Parameters:

timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

battery charge as a percentage.

Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.get_info(directive=None, timeout=None)

Returns a dictionary of information strings about the device.

Parameters:
  • directive
    information you want to get. Options are:
    • battery - battery charge as a percentage
    • disk - total, free, available bytes on disk
    • id - unique id of the device
    • os - name of the os
    • process - list of running processes (same as ps)
    • systime - system time of the device
    • uptime - uptime of the device

    If directive is None, will return all available information

  • timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.get_logcat(filter_specs=['dalvikvm:I', 'ConnectivityService:S', 'WifiMonitor:S', 'WifiStateTracker:S', 'wpa_supplicant:S', 'NetworkStateTracker:S'], format='time', filter_out_regexps=[], timeout=None, buffers=[])

Returns the contents of the logcat file as a list of strings.

Parameters:
  • filter_specs (list) – Optional logcat messages to be included.
  • format (str) – Optional logcat format.
  • filterOutRexps (list) – Optional logcat messages to be excluded.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • buffers (list) – Log buffers to retrieve. Valid buffers are “radio”, “events”, and “main”. Defaults to “main”.
Returns:

list of lines logcat output.

Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.get_prop(prop, timeout=None)

Gets value of a property from the device via adb shell getprop.

Parameters:
  • prop (str) – The propery name.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Returns:

string value of property.

Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.get_state(timeout=None)

Returns the device’s state via adb get-state.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

string value of adb get-state.

Raises:
  • ADBTimeoutError
  • ADBError

System control methods

ADBDevice.is_device_ready(timeout=None)

Abstract class that returns True if the device is ready.

Parameters:

timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.reboot(timeout=None)

Reboots the device.

Parameters:

timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError

reboot() reboots the device, issues an adb wait-for-device in order to wait for the device to complete rebooting, then calls is_device_ready() to determine if the device has completed booting.

File management methods

ADBDevice.chmod(path, recursive=False, mask='777', timeout=None, root=False)

Recursively changes the permissions of a directory on the device.

Parameters:
  • path (str) – The directory name on the device.
  • recursive (bool) – Flag specifying if the command should be executed recursively.
  • mask (str) – The octal permissions.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.cp(source, destination, recursive=False, timeout=None, root=False)

Copies a file or directory on the device.

Parameters:
  • source – string containing the path of the source file or directory.
  • destination – string containing the path of the destination file or directory.
  • recursive – optional boolean indicating if a recursive copy is to be performed. Required if the source is a directory. Defaults to False. Think cp -R source destination.
  • timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.exists(path, timeout=None, root=False)

Returns True if the path exists on the device.

Parameters:
  • path (str) – The directory name on the device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Returns:

boolean - True if path exists.

Raises:
  • ADBTimeoutError
  • ADBRootError
ADBDevice.get_file(remote, offset=None, length=None, timeout=None)

Pull file from device and return the file’s content

Parameters:
  • remote (str) – The path of the remote file.
  • offset – If specified, return only content beyond this offset.
  • length – If specified, limit content length accordingly.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.is_dir(path, timeout=None, root=False)

Returns True if path is an existing directory on the device.

Parameters:
  • path (str) – The path on the device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Returns:

boolean - True if path exists on the device and is a directory.

Raises:
  • ADBTimeoutError
  • ADBRootError
ADBDevice.is_file(path, timeout=None, root=False)

Returns True if path is an existing file on the device.

Parameters:
  • path (str) – The file name on the device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Returns:

boolean - True if path exists on the device and is a file.

Raises:
  • ADBTimeoutError
  • ADBRootError
ADBDevice.list_files(path, timeout=None, root=False)

Return a list of files/directories contained in a directory on the device.

Parameters:
  • path (str) – The directory name on the device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Returns:

list of files/directories contained in the directory.

Raises:
  • ADBTimeoutError
  • ADBRootError
ADBDevice.mkdir(path, parents=False, timeout=None, root=False)

Create a directory on the device.

Parameters:
  • path (str) – The directory name on the device to be created.
  • parents (bool) – Flag indicating if the parent directories are also to be created. Think mkdir -p path.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.mv(source, destination, timeout=None, root=False)

Moves a file or directory on the device.

Parameters:
  • source – string containing the path of the source file or directory.
  • destination – string containing the path of the destination file or directory.
  • timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.push(local, remote, timeout=None)

Pushes a file or directory to the device.

Parameters:
  • local (str) – The name of the local file or directory name.
  • remote (str) – The name of the remote file or directory name.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.pull(remote, local, timeout=None)

Pulls a file or directory from the device.

Parameters:
  • remote (str) – The path of the remote file or directory.
  • local (str) – The path of the local file or directory name.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.rm(path, recursive=False, force=False, timeout=None, root=False)

Delete files or directories on the device.

Parameters:
  • path (str) – The path of the remote file or directory.
  • recursive (bool) – Flag specifying if the command is to be applied recursively to the target. Default is False.
  • force (bool) – Flag which if True will not raise an error when attempting to delete a non-existent file. Default is False.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.rmdir(path, timeout=None, root=False)

Delete empty directory on the device.

Parameters:
  • path (str) – The directory name on the device.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.test_root

The test_root property returns the directory on the device where temporary test files are stored.

The first time test_root it is called it determines and caches a value for the test root on the device. It determines the appropriate test root by attempting to create a ‘dummy’ directory on each of a list of directories and returning the first successful directory as the test_root value.

The default list of directories checked by test_root are:

  • /storage/sdcard0/tests
  • /storage/sdcard1/tests
  • /sdcard/tests
  • /mnt/sdcard/tests
  • /data/local/tests

You may override the default list by providing a test_root argument to the ADBDevice constructor which will then be used when attempting to create the ‘dummy’ directory.

Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError

Process management methods

ADBDevice.get_process_list(timeout=None)

Returns list of tuples (pid, name, user) for running processes on device.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

list of (pid, name, user) tuples for running processes on the device.

Raises:
  • ADBTimeoutError
  • ADBError
ADBDevice.kill(pids, sig=None, attempts=3, wait=5, timeout=None, root=False)

Kills processes on the device given a list of process ids.

Parameters:
  • pids (list) – process ids to be killed.
  • sig (integer or None) – signal to be sent to the process.
  • attempts (integer) – number of attempts to try to kill the processes.
  • wait (integer) – number of seconds to wait after each attempt.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.pkill(appname, sig=None, attempts=3, wait=5, timeout=None, root=False)

Kills a processes on the device matching a name.

Parameters:
  • appname (str) – The app name of the process to be killed. Note that only the first 75 characters of the process name are significant.
  • sig (integer or None) – optional signal to be sent to the process.
  • attempts (integer) – number of attempts to try to kill the processes.
  • wait (integer) – number of seconds to wait after each attempt.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBRootError
  • ADBError
ADBDevice.process_exist(process_name, timeout=None)

Returns True if process with name process_name is running on device.

Parameters:
  • process_name (str) – The name of the process to check. Note that only the first 75 characters of the process name are significant.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.
Returns:

boolean - True if process exists.

Raises:
  • ADBTimeoutError
  • ADBError

ADBAndroid

class mozdevice.ADBAndroid(device=None, adb='adb', adb_host=None, adb_port=None, test_root='', logger_name='adb', timeout=300, verbose=False, device_ready_retry_wait=20, device_ready_retry_attempts=3)

ADBAndroid implements ADBDevice providing Android-specific functionality.

from mozdevice import ADBAndroid

adbdevice = ADBAndroid()
print(adbdevice.list_files("/mnt/sdcard"))
if adbdevice.process_exist("org.mozilla.fennec"):
    print("Fennec is running")

Informational methods

ADBAndroid.get_battery_percentage(timeout=None)

Returns the battery charge as a percentage.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

battery charge as a percentage.

Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.get_top_activity(timeout=None)

Returns the name of the top activity (focused app) reported by dumpsys

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

package name of top activity or None (cannot be determined)

Raises:
  • ADBTimeoutError
  • ADBError

System control methods

ADBAndroid.is_device_ready(timeout=None)

Checks if a device is ready for testing.

This method uses the android only package manager to check for readiness.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.power_on(timeout=None)

Sets the device’s power stayon value.

Parameters:

timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.reboot(timeout=None)

Reboots the device.

Parameters:

timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.

Raises:
  • ADBTimeoutError
  • ADBError

reboot() reboots the device, issues an adb wait-for-device in order to wait for the device to complete rebooting, then calls is_device_ready() to determine if the device has completed booting.

If the device supports running adbd as root, adbd will be restarted running as root. Then, if the device supports SELinux, setenforce Permissive will be called to change SELinux to permissive. This must be done after adbd is restarted in order for the SELinux Permissive setting to persist.

Application management methods

ADBAndroid.install_app(apk_path, replace=False, timeout=None)

Installs an app on the device.

Parameters:
  • apk_path (str) – The apk file name to be installed.
  • replace (bool) – If True, replace existing application.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.is_app_installed(app_name, timeout=None)

Returns True if an app is installed on the device.

Parameters:
  • app_name (str) – The name of the app to be checked.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.launch_application(app_name, activity_name, intent, url=None, extras=None, wait=True, fail_if_running=True, timeout=None)

Launches an Android application

Parameters:
  • app_name (str) – Name of application (e.g. com.android.chrome)
  • activity_name (str) – Name of activity to launch (e.g. .Main)
  • intent (str) – Intent to launch application with
  • url (str or None) – URL to open
  • extras (dict or None) – Extra arguments for application.
  • wait (bool) – If True, wait for application to start before returning.
  • fail_if_running (bool) – Raise an exception if instance of application is already running.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.launch_fennec(app_name, intent='android.intent.action.VIEW', moz_env=None, extra_args=None, url=None, wait=True, fail_if_running=True, timeout=None)

Convenience method to launch Fennec on Android with various debugging arguments

Parameters:
  • app_name (str) – Name of fennec application (e.g. org.mozilla.fennec)
  • intent (str) – Intent to launch application.
  • moz_env (str or None) – Mozilla specific environment to pass into application.
  • extra_args (str or None) – Extra arguments to be parsed by fennec.
  • url (str or None) – URL to open
  • wait (bool) – If True, wait for application to start before returning.
  • fail_if_running (bool) – Raise an exception if instance of application is already running.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.stop_application(app_name, timeout=None, root=False)

Stops the specified application

For Android 3.0+, we use the “am force-stop” to do this, which is reliable and does not require root. For earlier versions of Android, we simply try to manually kill the processes started by the app repeatedly until none is around any more. This is less reliable and does require root.

Parameters:
  • app_name (str) – Name of application (e.g. com.android.chrome)
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
  • root (bool) – Flag specifying if the command should be executed as root.
Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.uninstall_app(app_name, reboot=False, timeout=None)

Uninstalls an app on the device.

Parameters:
  • app_name (str) – The name of the app to be uninstalled.
  • reboot (bool) – Flag indicating that the device should be rebooted after the app is uninstalled. No reboot occurs if the app is not installed.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBAndroid.update_app(apk_path, timeout=None)

Updates an app on the device and reboots.

Parameters:
  • apk_path (str) – The apk file name to be updated.
  • timeout (integer or None) – The maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError

ADBB2G

class mozdevice.ADBB2G(device=None, adb='adb', adb_host=None, adb_port=None, test_root='', logger_name='adb', timeout=300, verbose=False, device_ready_retry_wait=20, device_ready_retry_attempts=3)

ADBB2G implements ADBDevice providing B2G-specific functionality.

from mozdevice import ADBB2G

adbdevice = ADBB2G()
print adbdevice.list_files("/mnt/sdcard")
if adbdevice.process_exist("b2g"):
    print "B2G is running"

Informational methods

ADBB2G.get_battery_percentage(timeout=None)

Returns the battery charge as a percentage.

Parameters:

timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

battery charge as a percentage.

Raises:
  • ADBTimeoutError
  • ADBError
ADBB2G.get_info(directive=None, timeout=None)

Returns a dictionary of information strings about the device.

Parameters:
  • directive
    information you want to get. Options are:
    • battery - battery charge as a percentage
    • disk - total, free, available bytes on disk
    • id - unique id of the device
    • memtotal - total memory available on the device
    • os - name of the os
    • process - list of running processes (same as ps)
    • systime - system time of the device
    • uptime - uptime of the device

    If directive is None, will return all available information

  • timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADB constructor is used.
Raises:
  • ADBTimeoutError
  • ADBError
ADBB2G.get_memory_total(timeout=None)

Returns the total memory available with units.

Parameters:

timeout – optional integer specifying the maximum time in seconds for any spawned adb process to complete before throwing an ADBTimeoutError. This timeout is per adb call. The total time spent may exceed this value. If it is not specified, the value set in the ADBDevice constructor is used.

Returns:

memory total with units.

Raises:
  • ADBTimeoutError
  • ADBError

ADBProcess

class mozdevice.ADBProcess(args)

ADBProcess encapsulates the data related to executing the adb process.

ADBError

exception mozdevice.ADBError

ADBError is raised in situations where a command executed on a device either exited with a non-zero exitcode or when an unexpected error condition has occurred. Generally, ADBErrors can be handled and the device can continue to be used.

ADBRootError

exception mozdevice.ADBRootError

ADBRootError is raised when a shell command is to be executed as root but the device does not support it. This error is fatal since there is no recovery possible by the script. You must either root your device or change your scripts to not require running as root.

ADBTimeoutError

exception mozdevice.ADBTimeoutError

ADBTimeoutError is raised when either a host command or shell command takes longer than the specified timeout to execute. The timeout value is set in the ADBCommand constructor and is 300 seconds by default. This error is typically fatal since the host is having problems communicating with the device. You may be able to recover by rebooting, but this is not guaranteed.

Recovery options are:

  • Killing and restarting the adb server via

    adb kill-server; adb start-server
    
  • Rebooting the device manually.

  • Rebooting the host.