adb_tool

class adb_tool.AdbTool(adb_command: AdbCommand | None = None, adb: str = 'adb', serial: str | None = None)[source]

Bases: object

A class to interact with an Android device using ADB commands and UI interactions.

capture_screenshot() → None[source]

Captures the current screen of the connected Android device.

capture_tree() → None[source]

Captures the current UI hierarchy of the connected Android device.

check_image(image_path: str, index: int = 0, is_capture: bool = False, match_threshold: float = 0.99, merge_threshold: int = 10) → bool[source]

Checks if the specified image is present on the screen.

Parameters:

  • image_path – Path to the image file to search for.

  • index – Index of the matching image rectangle to use, defaults to 0.

  • is_capture – Whether to capture the screen before searching, defaults to False.

  • match_threshold – Threshold for image matching, defaults to 0.99.

  • merge_threshold – Threshold for merging close rectangles, defaults to 10.

Returns:

True if the image is found, False otherwise.

check_resource_id(resource_id: str, index: int = 0, root_node: UINode | None = None, is_capture: bool = False) → bool[source]

Checks if a node with the specified resource-id exists.

Parameters:

  • resource_id – The resource-id to search for.

  • index – The index of the matching node to return, defaults to 0.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

True if the node exists, False otherwise.

check_text(text: str, index: int = 0, root_node: UINode | None = None, is_capture: bool = False) → bool[source]

Checks if a node with the specified text exists.

Parameters:

  • text – The text to search for.

  • index – The index of the matching node to return, defaults to 0.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

True if the node exists, False otherwise.

content_screen() → ndarray[source]

Returns the captured screen as an OpenCV image.

Returns:

The captured screen as an OpenCV image.

content_tree() → UINode[source]

Returns the root node of the captured UI hierarchy.

Returns:

The root UINode.

find_image(image_path: str, index: int = 0, is_capture: bool = False, match_threshold: float = 0.99, merge_threshold: int = 10) → tuple[int, int, int, int] | None[source]

Finds the specified image on the screen and returns the rectangle of the match.

Parameters:

  • image_path – Path to the image file to search for.

  • index – Index of the matching image rectangle to return, defaults to 0.

  • is_capture – Whether to capture the screen before searching, defaults to False.

  • match_threshold – Threshold for image matching, defaults to 0.99.

  • merge_threshold – Threshold for merging close rectangles, defaults to 10.

Returns:

The rectangle of the found image, or None if not found.

find_images(image_path: str, match_threshold: float = 0.99, merge_threshold: int = 10) → list[tuple[int, int, int, int]][source]

Finds instances of a specified image within the captured screen image.

Parameters:

  • image_path – Path to the image file to search for.

  • match_threshold – Threshold for image matching, defaults to 0.99.

  • merge_threshold – Threshold for merging close rectangles, defaults to 10.

Returns:

A list of rectangles where the image was found.

find_resource_id(resource_id: str, index: int = 0, root_node: UINode | None = None, is_capture: bool = False) → UINode | None[source]

Finds a node by its resource-id attribute.

Parameters:

  • resource_id – The resource-id to search for.

  • index – The index of the matching node to return, defaults to 0.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

The matching UINode, or None if not found.

find_text(text: str, index: int = 0, root_node: UINode | None = None, is_capture: bool = False) → UINode | None[source]

Finds a node by its text attribute.

Parameters:

  • text – The text to search for.

  • index – The index of the matching node to return, defaults to 0.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

The matching UINode, or None if not found.

find_texts(text: str, root_node: UINode | None = None, is_capture: bool = False) → list[UINode][source]

Finds nodes by their text attribute.

Parameters:

  • text – The text to search for.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

A list of matching UINodes.

logcat(output_file: TextIOWrapper | None = None, cmd: str = '') → LogcatContext[source]

Starts a logcat subprocess and returns a LogcatContext for managing it.

Parameters:

  • output_file – The file to which logcat output is written, defaults to None.

  • cmd – Additional logcat command options, defaults to an empty string.

Returns:

A LogcatContext instance.

logcat_clear(cmd: str = '') → CompletedProcess[source]

Clears the logcat logs on the device.

Parameters:

cmd – Additional logcat command options, defaults to an empty string.

Returns:

The completed process.

logcat_dump(cmd: str = '') → CompletedProcess[source]

Dumps the logcat logs from the device.

Parameters:

cmd – Additional logcat command options, defaults to an empty string.

Returns:

The completed process.

query(cmd: str, stdout=-1, stderr=-1) → CompletedProcess[source]

Executes an ADB command and waits for it to complete.

Parameters:

  • cmd – The command to execute.

  • stdout – Standard output pipe, defaults to subprocess.PIPE.

  • stderr – Standard error pipe, defaults to subprocess.PIPE.

Returns:

The completed process.

query_async(cmd: str, stdout=-1, stderr=-1) → Popen[source]

Executes an ADB command asynchronously.

Parameters:

  • cmd – The command to execute.

  • stdout – Standard output pipe, defaults to subprocess.PIPE.

  • stderr – Standard error pipe, defaults to subprocess.PIPE.

Returns:

The process object.

touch_image(image_path: str, index: int = 0, is_capture: bool = False, match_threshold: float = 0.99, merge_threshold: int = 10) → bool[source]

Simulates a tap on the screen at the center of the specified image if found.

Parameters:

  • image_path – Path to the image file to search for.

  • index – Index of the matching image rectangle to use, defaults to 0.

  • is_capture – Whether to capture the screen before searching, defaults to False.

  • match_threshold – Threshold for image matching, defaults to 0.99.

  • merge_threshold – Threshold for merging close rectangles, defaults to 10.

Raises:

ValueError – If the image is not found.

Returns:

True if the tap was successful, False otherwise.

touch_resource_id(resource_id: str, index: int = 0, root_node: UINode | None = None, is_capture: bool = False) → bool[source]

Simulates a tap on the node with the specified resource-id.

Parameters:

  • resource_id – The resource-id to search for.

  • index – The index of the matching node to return, defaults to 0.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

True if the tap was successful, False otherwise.

touch_text(text: str, index: int = 0, root_node: UINode | None = None, is_capture: bool = False) → bool[source]

Simulates a tap on the node with the specified text.

Parameters:

  • text – The text to search for.

  • index – The index of the matching node to return, defaults to 0.

  • root_node – The root node to start the search from, defaults to None.

  • is_capture – Whether to capture the UI hierarchy before searching, defaults to False.

Returns:

True if the tap was successful, False otherwise.

class adb_tool.LogcatContext(subprocess: Popen, file: TextIOWrapper, is_delete: bool = True)[source]

Bases: object

A context manager for handling logcat subprocesses and output files.

close() → None[source]

Closes the logcat output file and terminates the subprocess.

open(mode: str = 'r') → TextIOWrapper[source]

Opens the logcat output file.

Parameters:

mode – The mode in which to open the file, defaults to ‘r’.

Returns:

The opened file.