Developer Interface

This part of the documentation covers all the interfaces of Cerium. For parts where Cerium depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Main Interface

All of Cerium’ functionality can be accessed by an instance of the AndroidDriver object.

class cerium.AndroidDriver(executable_path: str = 'default', device_sn: str = None, wireless: bool = False, host: str = '192.168.0.3', port: str = 5555, service_port: str = 5037, env: dict = None, service_args: list = None, dev: bool = False)[source]

More utility functions are implemented.

Controls Android Debug Bridge and allows you to drive the android device.

app_broadcast(*args) → None

Send a broadcast.

app_start_action(*args) → None

Start action.

app_start_activity(*args) → None

Start activity.

app_start_category(*args) → None

Start category.

app_start_service(*args) → None

Start a service.

app_start_up_time(package: str) → str

Get the time it took to launch your application.

app_stop_service(*args) → None

Stop a service

app_trim_memory(pid: int, level: str = 'RUNNING_LOW') → None

Trim memory.

Args:
level: HIDDEN | RUNNING_MODERATE | BACKGROUNDRUNNING_LOW | MODERATE | RUNNING_CRITICAL | COMPLETE
auto_connect(port: int = 5555) → None

Connect to a device via TCP/IP automatically.

back() → None[source]

Back button.

brightness_down() → None[source]

Brightness down.

brightness_up() → None[source]

Brightness up

clear_app_data(package: str) → None

Deletes all data associated with a package.

click(x: int, y: int) → None

Simulate finger click.

close_app(package: str) → None

Close an application.

connect(host: str = '192.168.0.3', port: Union[int, str] = 5555) → None

Connect to a device via TCP/IP directly.

devices() → list

List connected devices.

devices_l() → Dict[KT, VT]

List connected devices (-l for long output).

disconnect(host: str = '192.168.0.3', port: Union[int, str] = 5555) → None

Disconnect from given TCP/IP device [default port=5555].

disconnect_all() → None

Disconnect all.

end_the_call() → None[source]

End the current call.

execute(*, args: Union[list, tuple], options: dict) → tuple

Execute command.

fastboot() → None

Reboot to bootloader mode.

find_element(value, by='resource-id', update=False) → cerium.elements.Elements

Find a element or the first element.

find_element_by_class(class_, update=False) → cerium.elements.Elements

Finds an element by class.

Args:
class_: The class of the element to be found. update: If the interface has changed, this option should be True.
Returns:
The element if it was found.
Raises:
NoSuchElementException - If the element wasn’t found.
Usage:
element = driver.find_element_by_class(‘foo’)
find_element_by_id(id_, update=False) → cerium.elements.Elements

Finds an element by id.

Args:
id_: The id of the element to be found. update: If the interface has changed, this option should be True.
Returns:
The element if it was found.
Raises:
NoSuchElementException - If the element wasn’t found.
Usage:
element = driver.find_element_by_id(‘foo’)
find_element_by_name(name, update=False) → cerium.elements.Elements

Finds an element by name.

Args:
name: The name of the element to be found. update: If the interface has changed, this option should be True.
Returns:
The element if it was found.
Raises:
NoSuchElementException - If the element wasn’t found.
Usage:
element = driver.find_element_by_name(‘foo’)
find_elements(value, by='resource-id', update=False) → cerium.elements.Elements

Find all elements.

find_elements_by_class(class_, update=False) → cerium.elements.Elements

Finds multiple elements by class.

Args:
class_: The class of the elements to be found. update: If the interface has changed, this option should be True.
Returns:
A list with elements if any was found. An empty list if not.
Raises:
NoSuchElementException - If the element wasn’t found.
Usage:
elements = driver.find_elements_by_class(‘foo’)
find_elements_by_id(id_, update=False) → cerium.elements.Elements

Finds multiple elements by id.

Args:
id_: The id of the elements to be found. update: If the interface has changed, this option should be True.
Returns:
A list with elements if any was found. An empty list if not.
Raises:
NoSuchElementException - If the element wasn’t found.
Usage:
elements = driver.find_elements_by_id(‘foo’)
find_elements_by_name(name, update=False) → cerium.elements.Elements

Finds multiple elements by name.

Args:
name: The name of the elements to be found. update: If the interface has changed, this option should be True.
Returns:
A list with elements if any was found. An empty list if not.
Raises:
NoSuchElementException - If the element wasn’t found.
Usage:
elements = driver.find_elements_by_name(‘foo’)
get_android_id() → str

Show Android ID.

get_android_version() → str

Show Android version.

get_battery_info() → dict

Show device battery information.

Returns:

A dict. For example:

{‘AC powered’: ‘false’, ‘Charge counter’: ‘0’, ‘Max charging current’: ‘0’, ‘Max charging voltage’: ‘0’, ‘USB powered’: ‘false’, ‘Wireless powered’: ‘false’, ‘health’: ‘2’, ‘level’: ‘67’, ‘present’: ‘true’, ‘scale’: ‘100’, ‘status’: ‘3’, ‘technology’: ‘Li-poly’, ‘temperature’: ‘310’, ‘voltage’: ‘3965’}
get_cpu_info() → str

Show device CPU information.

get_device_mac() → str

Show device MAC.

get_device_model() → str

Show device model.

get_displays_params() → str

Show displays parameters.

get_ip_addr() → str

Show IP Address.

get_memory_info() → str

Show device memory information.

get_resolution() → list

Show device resolution.

get_screen_density() → str

Show device screen density (PPI).

get_sdk_version() → str

Show Android SDK version.

get_state() → str

offline | bootloader | device

home() → None[source]

Home button. Go back to Home screen.

install(package: str, option: str = '-r') → None

Push package to the device and install it.

Args:
option:
-l: forward lock application -r: replace existing application -t: allow test packages -s: install application on sdcard -d: allow version code downgrade (debuggable packages only) -g: grant all runtime permissions
install_multiple(*packages, option: str = '-r') → None

Push packages to the device and install them.

Args:
option:
-l: forward lock application -r: replace existing application -t: allow test packages -s: install application on sdcard -d: allow version code downgrade (debuggable packages only) -p: partial application install (install-multiple only) -g: grant all runtime permissions
kill_server() → None

Kill the server if it is running.

launch_app(package) → None[source]

Launch an application.

lock() → None[source]

Lock screen.

long_press(x: int, y: int, duration: int = 1000) → None

Simulate finger long press somewhere. (1000ms = 1s)

make_a_call(number: int = 18268237856) → None[source]

Make a call.

menu() → None[source]

Menu button. Open the menu or show recent apps tray.

open_browser() → None[source]

Open the system browser.

open_calculator() → None[source]

Open the system calculator

open_calendar() → None[source]

Open the system calendar.

open_contacts() → None[source]

Open the system contacts.

open_url(url: str = 'https://www.baidu.com') → None[source]

Open a web page with the default browser.

paste() → None[source]

Paste from clipboard.

power() → None[source]

Power button.

pull(remote: str, local: str) → None

Copy files/directories from device.

pull_a(remote: str, local: str) → None

Copy files/directories from device, and preserve file timestamp and mode.

pull_screencap(remote: str = '/sdcard/screencap.png', local: str = 'screencap.png') → None

Taking a screenshot of a device display, then copy it to your computer.

pull_screenrecord(bit_rate: int = 5000000, time_limit: int = 180, remote: str = '/sdcard/demo.mp4', local: str = 'demo.mp4') → None

Recording the display of devices running Android 4.4 (API level 19) and higher. Then copy it to your computer.

Args:
bit_rate:You can increase the bit rate to improve video quality, but doing so results in larger movie files. time_limit: Sets the maximum recording time, in seconds, and the maximum value is 180 (3 minutes).
push(local: str = 'LICENSE', remote: str = '/sdcard/LICENSE') → None

Copy local files/directories to device.

push_sync(local: str = 'LICENSE', remote: str = '/sdcard/LICENSE') → None

Only push files that are newer on the host than the device.

reboot() → None

Reboot the device.

recovery() → None

Reboot to recovery mode.

restart() → None

Restart the server if it is running.

restart_server() → None

Restart the server if it is running.

root() → None

Restart adbd with root permissions.

screencap(filename: str = '/sdcard/screencap.png') → None

Taking a screenshot of a device display.

screencap_exec(filename: str = 'screencap.png') → None

Taking a screenshot of a device display, then copy it to your computer.

screenrecord(bit_rate: int = 5000000, time_limit: int = 180, filename: str = '/sdcard/demo.mp4') → None

Recording the display of devices running Android 4.4 (API level 19) and higher.

Args:
bit_rate:You can increase the bit rate to improve video quality, but doing so results in larger movie files. time_limit: Sets the maximum recording time, in seconds, and the maximum value is 180 (3 minutes).
send_keyevents(keyevent: int) → None

Simulates typing keyevents.

send_keyevents_long_press(keyevent: int) → None

Simulates typing keyevents long press.

send_keys(text: str = 'cerium') → None

Simulates typing keys.

send_monkey(*args) → None

Generate pseudo-random user events to simulate clicks, touches, gestures, etc.

classmethod serial_matcher(serial) → bool

Returns a device matcher for the given serial.

serial_number

Show device serial number.

service_args() → str

Parameters when starting the service.

service_tcp

Gets the TCP of the Service.

start() → None

Starts the Service.

start_server() → None

Start server.

stop() → None

Stops the service.

swipe(x1: int, y1: int, x2: int, y2: int, duration: int = 100) → None

Simulate finger swipe. (1000ms = 1s)

swipe_down(width: int = 1080, length: int = 1920) → None[source]

Swipe down.

swipe_left(width: int = 1080, length: int = 1920) → None[source]

Swipe left.

swipe_right(width: int = 1080, length: int = 1920) → None[source]

Swipe right.

swipe_up(width: int = 1080, length: int = 1920) → None[source]

Swipe up.

switch() → None[source]

Show recent apps tray.

sync(option: str = 'all') → None

Sync a local build from $ANDROID_PRODUCT_OUT to the device (default all).

Args:
option: ‘system’, ‘vendor’, ‘oem’, ‘data’, ‘all’
sync_l(option: str = 'all') → None

List but don’t copy.

Args:
option: ‘system’, ‘vendor’, ‘oem’, ‘data’, ‘all’
tcpip(port: int = 5555) → None

Restart adb server listening on TCP on PORT.

uidump(local: str = None) → None

Get the current interface layout file.

uninstall(package: str) → None

Remove this app package from the device.

uninstall_k(package: str) → None

Remove this app package from the device, and keep the data and cache directories.

unlock(password, width=1080, length=1920) → None[source]

Unlock screen.

unroot() → None

Restart adbd without root permissions.

version() → str

Show the version number of Android Debug Bridge.

view_current_app_behavior() → str

View application behavior in the current window.

view_focused_activity() → str

View focused activity.

view_package_info(package: str = '') → str

View package detail information.

view_package_path(package: str) → str

Print the path to the APK of the given.

view_packgets_list(option: str = '-e', keyword: str = '') → list

Show all packages.

Args:
option:
-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 -keyword: optionally only those whose name contains the text in keyword
view_running_services(package: str = '') → str

View running services.

view_surface_app_activity() → str

Get package with activity of applications that are running in the foreground.

volume_down() → None[source]

Volume down.

volume_mute() → None[source]

Volume mute.

volume_up() → None[source]

Volume up.

wake() → None[source]

Wake up screen.

Exceptions

exception cerium.ApplicationsException[source]

Thrown when using the wrong command to run the application.

exception cerium.CharactersException[source]

Thrown when a character error occurs.

exception cerium.DeviceConnectionException[source]

Thrown when no devices are connected.

exception cerium.NoSuchElementException[source]

Thrown when the element could not be found.

exception cerium.NoSuchPackageException[source]

Thrown when the package does not exist.