airtest.core.android.adb module

class ADB(serialno=None, adb_path=None, server_addr=None, display_id=None, input_event=None)

Bases: object

adb client object class

status_device = 'device'

status_offline = 'offline'

SHELL_ENCODING = 'utf-8'

static get_adb_path()

Returns the path to the adb executable.

Checks if adb process is running, returns the running process path.

If adb process is not running, checks if ANDROID_HOME environment variable is set. Constructs the adb path using ANDROID_HOME and returns it if set.

If adb process is not running and ANDROID_HOME is not set, uses built-in adb path.

Returns:

The path to the adb executable.

Return type:

str

static builtin_adb_path()

Return built-in adb executable path

Returns:

adb executable path

start_server()

Perform adb start-server command to start the adb server

Returns:

None

kill_server()

Perform adb kill-server command to kill the adb server

Returns:

None

version()

Perform adb version command and return the command output

Returns:

command output

start_cmd(cmds, device=True)

Start a subprocess with adb command(s)

Parameters:

• cmds – command(s) to be run

• device – if True, the device serial number must be specified by -s serialno argument

Raises:

RuntimeError – if device is True and serialno is not specified

Returns:

a subprocess

cmd(cmds, device=True, ensure_unicode=True, timeout=None)

Run the adb command(s) in subprocess and return the standard output

Parameters:

• cmds – command(s) to be run

• device – if True, the device serial number must be specified by -s serialno argument

• ensure_unicode – encode/decode unicode of standard outputs (stdout, stderr)

• timeout – timeout in seconds

Raises:

• DeviceConnectionError – if any error occurs when connecting the device

• AdbError – if any other adb error occurs

Returns:

command(s) standard output (stdout)

close_proc_pipe(proc)

close stdin/stdout/stderr of subprocess.Popen.

devices(state=None)

Perform adb devices command and return the list of adb devices

Parameters:

state – optional parameter to filter devices in specific state

Returns:

list od adb devices

connect(force=False)

Perform adb connect command, remote devices are preferred to connect first

Parameters:

force – force connection, default is False

Returns:

None

disconnect()

Perform adb disconnect command

Returns:

None

get_status()

Perform adb get-state and return the device status

Raises:

AdbError – if status cannot be obtained from the device

Returns:

None if status is not found, otherwise return the standard output from adb get-state command

wait_for_device(timeout=5)

Perform adb wait-for-device command

Parameters:

timeout – time interval in seconds to wait for device

Raises:

DeviceConnectionError – if device is not available after timeout

Returns:

None

start_shell(cmds)

Handle adb shell command(s)

Parameters:

cmds – adb shell command(s)

Returns:

None

raw_shell(cmds, ensure_unicode=True)

Handle adb shell command(s) with unicode support

Parameters:

• cmds – adb shell command(s)

• ensure_unicode – decode/encode unicode True or False, default is True

Returns:

command(s) output

shell(cmd)

Run the adb shell command on the device

Parameters:

cmd – a command to be run

Raises:

AdbShellError – if command return value is non-zero or if any other AdbError occurred

Returns:

command output

keyevent(keyname)

Perform adb shell input keyevent command on the device

Parameters:

keyname – key event name

Returns:

None

getprop(key, strip=True)

Perform adb shell getprop on the device

Parameters:

• key – key value for property

• strip – True or False to strip the return carriage and line break from returned string

Returns:

propery value

property sdk_version

Get the SDK version from the device

Returns:

SDK version

push(local, remote)

Push file or folder to the specified directory to the device

Parameters:

• local – local file or folder to be copied to the device

• remote – destination on the device where the file will be copied

Returns:

The file path saved in the phone may be enclosed in quotation marks, eg. ‘“testfile.txt”’

Examples

>>> adb = device().adb
>>> adb.push("test.txt", "/data/local/tmp")

>>> new_name = adb.push("test space.txt", "/data/local/tmp")  # test the space in file name
>>> print(new_name)
"/data/local/tmp/test\ space.txt"
>>> adb.shell("rm " + new_name)

>>> adb.push("test_dir", "/sdcard/Android/data/com.test.package/files")
>>> adb.push("test_dir", "/sdcard/Android/data/com.test.package/files/test_dir")

pull(remote, local='')

Perform adb pull command

Parameters:

• remote – remote file to be downloaded from the device

• local – local destination where the file will be downloaded from the device

Note

If <=PY3, the path in Windows cannot be the root directory, and cannot contain symbols such as /g in the path 注意：如果低于PY3,windows中路径不能为根目录，并且不能包含/g等符号在路径里

Returns:

None

forward(local, remote, no_rebind=True)

Perform adb forward command

Parameters:

• local – local tcp port to be forwarded

• remote – tcp port of the device where the local tcp port will be forwarded

• no_rebind – True or False

Returns:

None

get_forwards()

Perform `adb forward –list`command

Yields:

serial number, local tcp port, remote tcp port

Returns:

None

classmethod get_available_forward_local()

Generate a pseudo random number between 11111 and 50000 that will be used as local forward port

Returns:

integer between 11111 and 50000

Note

use forward –no-rebind to check if port is available

setup_forward(device_port, no_rebind=True)

Generate pseudo random local port and check if the port is available.

Parameters:

• device_port – it can be string or the value of the function(localport), e.g. “tcp:5001” or “localabstract:{}”.format

• no_rebind – adb forward –no-rebind option

Returns:

local port and device port

remove_forward(local=None)

Perform adb forward –remove command

Parameters:

local – local tcp port

Returns:

None

install_app(filepath, replace=False, install_options=None)

Perform adb install command

Parameters:

• filepath – full path to file to be installed on the device

• replace –

  force to replace existing application, default is False

  e.g.[“-t”, # allow test packages

  ”-l”, # forward lock application, “-s”, # install application on sdcard, “-d”, # allow version code downgrade (debuggable packages only) “-g”, # grant all runtime permissions

  ]

Returns:

command output

install_multiple_app(filepath, replace=False, install_options=None)

Perform adb install-multiple command

Parameters:

• filepath – full path to file to be installed on the device

• replace – force to replace existing application, default is False

• install_options –

  list of options e.g.[“-t”, # allow test packages

  ”-l”, # forward lock application, “-s”, # install application on sdcard, “-d”, # allow version code downgrade (debuggable packages only) “-g”, # grant all runtime permissions “-p”, # partial application install (install-multiple only)

  ]

Returns:

command output

pm_install(filepath, replace=False, install_options=None)

Perform adb push and adb install commands

Note

This is more reliable and recommended way of installing .apk files

Parameters:

• filepath – full path to file to be installed on the device

• replace – force to replace existing application, default is False

• install_options –

  list of options e.g.[“-t”, # allow test packages

  ”-l”, # forward lock application, “-s”, # install application on sdcard, “-d”, # allow version code downgrade (debuggable packages only) “-g”, # grant all runtime permissions

  ]

Returns:

None

uninstall_app(package)

Perform adb uninstall command :param package: package name to be uninstalled from the device

Returns:

command output

pm_uninstall(package, keepdata=False)

Perform adb uninstall command and delete all related application data

Parameters:

• package – package name to be uninstalled from the device

• keepdata – True or False, keep application data after removing the app from the device

Returns:

command output

snapshot()

Take the screenshot of the device display

Returns:

command output (stdout)

touch(tuple_xy)

Perform user input (touchscreen) on given coordinates

Parameters:

tuple_xy – coordinates (x, y)

Returns:

None

swipe(tuple_x0y0, tuple_x1y1, duration=500)

Perform user input (swipe screen) from start point (x,y) to end point (x,y)

Parameters:

• tuple_x0y0 – start point coordinates (x, y)

• tuple_x1y1 – end point coordinates (x, y)

• duration – time interval for action, default 500

Raises:

AirtestError – if SDK version is not supported

Returns:

None

logcat(grep_str='', extra_args='', read_timeout=10)

Perform adb shell logcat command and search for given patterns

Parameters:

• grep_str – pattern to filter from the logcat output

• extra_args – additional logcat arguments

• read_timeout – time interval to read the logcat, default is 10

Yields:

logcat lines containing filtered patterns

Returns:

None

exists_file(filepath)

Check if the file exits on the device

Parameters:

filepath – path to the file

Returns:

True or False if file found or not

file_size(filepath)

Get the file size

Parameters:

filepath – path to the file

Returns:

The file size

Raises:

AdbShellError if no such file –

property line_breaker

Set carriage return and line break property for various platforms and SDK versions

Returns:

carriage return and line break string

property display_info

Set device display properties (orientation, rotation and max values for x and y coordinates)

Notes: if there is a lock screen detected, the function tries to unlock the device first

Returns:

device screen properties

get_display_info()

Get information about device physical display (orientation, rotation and max values for x and y coordinates)

Returns:

device screen properties e.g {

’width’: 1440, ‘height’: 2960, ‘density’: 4.0, ‘orientation’: 3, ‘rotation’: 270, ‘max_x’: 4095, ‘max_y’: 4095

}

getMaxXY()

Get device display maximum values for x and y coordinates

Returns:

max x and max y coordinates

getRestrictedScreen()

Get value for mRestrictedScreen (without black border / virtual keyboard)`

Returns:

screen resolution mRestrictedScreen value as tuple (x, y)

getPhysicalDisplayInfo()

Get value for display dimension and density from mPhysicalDisplayInfo value obtained from dumpsys command.

Returns:

physical display info for dimension and density

getDisplayOrientation()

Another way to get the display orientation, this works well for older devices (SDK version 15)

Returns:

display orientation information

update_cur_display(display_info)

Some phones support resolution modification, try to get the modified resolution from dumpsys adb shell dumpsys window displays | find “cur=”

本方法虽然可以更好地获取到部分修改过分辨率的手机信息 但是会因为cur=(d+)x(d+)的数值在不同设备上width和height的顺序可能不同，导致横竖屏识别出现问题 airtest不再使用本方法作为通用的屏幕尺寸获取方法，但依然可用于部分设备获取当前被修改过的分辨率

Examples

>>> # 部分三星和华为设备，若分辨率没有指定为最高，可能会导致点击偏移，可以用这个方式强制修改：
>>> # For some Samsung and Huawei devices, if the resolution is not specified as the highest,
>>> # it may cause click offset, which can be modified in this way:
>>> dev = device()
>>> info = dev.display_info
>>> info2 = dev.adb.update_cur_display(info)
>>> dev.display_info.update(info2)

Parameters:

display_info – the return of self.getPhysicalDisplayInfo()

Returns:

display_info

get_top_activity()

Perform adb shell dumpsys activity top command search for the top activity

Raises:

AirtestError – if top activity cannot be obtained

Returns:

(package_name, activity_name, pid)

Return type:

top activity as a tuple

is_keyboard_shown()

Perform adb shell dumpsys input_method command and search for information if keyboard is shown

Returns:

True or False whether the keyboard is shown or not

is_screenon()

Perform adb shell dumpsys window policy command and search for information if screen is turned on or off

Raises:

AirtestError – if screen state can’t be detected

Returns:

True or False whether the screen is turned on or off

is_locked()

Perform adb shell dumpsys window policy command and search for information if screen is locked or not

Raises:

AirtestError – if lock screen can’t be detected

Returns:

True or False whether the screen is locked or not

unlock()

Perform adb shell input keyevent MENU and adb shell input keyevent BACK commands to attempt to unlock the screen

Returns:

None

Warning

Might not work on all devices

get_package_version(package)

Perform adb shell dumpsys package and search for information about given package version

Parameters:

package – package name

Returns:

None if no info has been found, otherwise package version

list_app(third_only=False)

Perform adb shell pm list packages to print all packages, optionally only

those whose package name contains the text in FILTER.

Options

-f: see their associated file -d: filter to only show disabled packages -e: filter to only show enabled packages -s: filter to only show system packages -3: filter to only show third party packages -i: see the installer for the packages -u: also include uninstalled packages

Parameters:

third_only – print only third party packages

Returns:

list of packages

path_app(package)

Perform adb shell pm path command to print the path to the package

Parameters:

package – package name

Raises:

• AdbShellError – if any adb error occurs

• AirtestError – if package is not found on the device

Returns:

path to the package

check_app(package)

Perform adb shell dumpsys package command and check if package exists on the device

Parameters:

package – package name

Raises:

AirtestError – if package is not found

Returns:

True if package has been found

start_app(package, activity=None)

Perform adb shell monkey commands to start the application, if activity argument is None, then adb shell am start command is used.

Parameters:

• package – package name

• activity – activity name

Returns:

None

start_app_timing(package, activity)

Start the application and activity, and measure time

Parameters:

• package – package name

• activity – activity name

Returns:

app launch time

stop_app(package)

Perform adb shell am force-stop command to force stop the application

Parameters:

package – package name

Returns:

None

clear_app(package)

Perform adb shell pm clear command to clear all application data

Parameters:

package – package name

Returns:

None

text(content)

Use adb shell input for text input

Parameters:

content – text to input

Returns:

None

Examples

>>> dev = connect_device("Android:///")
>>> dev.text("Hello World")
>>> dev.text("test123")

get_ip_address()

Perform several set of commands to obtain the IP address.

• adb shell netcfg | grep wlan0

• adb shell ifconfig

• adb getprop dhcp.wlan0.ipaddress

Returns:

None if no IP address has been found, otherwise return the IP address

get_gateway_address()

Perform several set of commands to obtain the gateway address.

• adb getprop dhcp.wlan0.gateway

• adb shell netcfg | grep wlan0

Returns:

None if no gateway address has been found, otherwise return the gateway address

get_memory()

get_storage()

get_cpuinfo()

get_cpufreq()

get_cpuabi()

get_gpu()

get_model()

get_manufacturer()

get_device_info()

Get android device information, including: memory/storage/display/cpu/gpu/model/manufacturer…

Returns:

Dict of info

get_display_of_all_screen(info, package=None)

Perform adb shell dumpsys window windows commands to get window display of application.

Parameters:

• info – device screen properties

• package – package name, default to the package of top activity

Returns:

None if adb command failed to run, otherwise return device screen properties(portrait mode) eg. (offset_x, offset_y, screen_width, screen_height)

cleanup_adb_forward()