This document provides a comprehensive guide to using the qa_automation class within qautomationcore.py. This class is a wrapper around uiautomator2 designed to simplify Android UI automation tasks.

from qa_automation2.qautomationcore import qa_automation

# Initialize with a connected device
# device: uiautomator2 device object
# device_infor: dictionary containing device information (e.g., model)
# log_dir: directory to save logs
qa = qa_automation(device=d, device_infor={"model": "Pixel_4"}, log_dir="logs")

Finds a single UI element based on various criteria.

• Parameters:
  • name: The identifier string (text, resource-id, xpath, etc.) or a list of strings.
  • type_: The type of identifier. Options: text, text_contains, resource_id, xpath, class_name, talkback, etc.
  • index: Index of the element if multiple match (default 0).
• Returns: The UI object if found, otherwise False.

Finds all matching UI elements on the screen.

• Parameters: Similar to Find_element but without index.
• Returns: A list of UI objects. If name is a list of strings, it aggregates and returns all matches.

Waits for an element to appear within a timeout period.

• Parameters: Same as Find_element, plus timeout (seconds).
• Returns: The UI object if found, otherwise False.

Waits for an element to disappear from the screen within a timeout period.

• Parameters: name, type_, timeout.
• Returns: True if it successfully disappears, otherwise False.

Finds an element and returns its exact center coordinates (X, Y).

• Returns: A tuple (center_x, center_y) or False if not found.

Finds an element and performs a click (or long click).

• Parameters: Same as Find_element, plus long_ (bool) for long press.
• Returns: True if successful.

Inputs text into an element or the currently focused field.

• Parameters:
  • text: The string to input.
  • name, type_, index: To find the target element (optional).
  • clear: Clears existing text before inputting.
  • press_enter: Presses the Enter key after inputting.
  • click_before: Clicks the element before inputting (default True).

Clicks an element located relative to an anchor text (e.g., click a specific Radio Button next to a label).

• Parameters:
  • anchor_text: The text to use as a reference point.
  • target_type: The type of element to click (radio, checkbox, switch, button, edit).
  • direction: Direction to look for the target (left, right, up, down, sibling).
• Example: qa.click_element_relative("Gender", "radio", "right")

Clicks a specific child element within a parent container.

• Parameters:
  • parent_name, parent_type: Identifiers for the parent container.
  • child_name, child_type: Identifiers for the child element inside the parent.
  • child_index: Index of the child if multiple match (default 0).

Performs a simple scroll gesture.

• Parameters:
  • type_: Direction (up, down, left, right, top, bottom).
  • scale, box, duration, steps: Fine-tuning scroll behavior.

Scrolls in a specified direction until the element is found.

• Parameters: Element identifiers plus type_scroll, max_scrolls.

Scrolls one way (e.g., UP) then the other (e.g., DOWN) to find an element (and optionally click it).

Simulates a physical key press.

• Keys: home, back, recent, enter, delete, volume_up, power, etc.
• Example: qa.press_key("home")

Controls the device screen state.

• Actions: check (returns status), on (turn screen on), off (turn screen off).

Performs a pinch-to-zoom gesture.

• Parameters:
  • action: in (zoom in/shrink), out (zoom out/expand).
  • percent: Size of the pinch gesture.
  • element_name: Optional, to perform zoom on a specific element.

Starts or stops an application by package name.

Clears the cache and data of an application (like a fresh reinstall).

• Parameters: package_name.

Retrieves information about the currently running app and activity on the screen.

• Returns: A dictionary with package and activity keys.

Installs an app from a local APK path or uninstalls it by package name.

Waits for a specific app activity (screen) to load.

Executes an ADB shell command on the device.

Retrieves text or content descriptions from all matching elements or children of an element.

Extracts specific properties (bounds, text, checked, enabled, etc.) from an element object.

Drags an element to another element or specific coordinates.

• Parameters: source_name, dest_name (or dest_x, dest_y), duration.

Double clicks on an element.

• Parameters: name, type_.

Performs raw pointer/touch actions at specific screen coordinates.

• Parameters: action (down, move, up), x, y.

Performs a direct coordinate-to-coordinate swipe gesture.

• Parameters: fx, fy (from), tx, ty (to), duration.

Captures a screenshot and saves it to a file on your PC.

• Parameters: filename (Absolute or relative path).

Records the screen video. start_recording initiates the process, and stop_recording stops it and pulls the .mp4 file directly to your PC.

• Parameters: pc_filename for starting the recording.

Transfers files between the PC and the connected Android device.

• Parameters: pc_path, device_path.

Opens system panels.

• Parameters: target (notification, quick_settings).

Sets or retrieves text from the device clipboard.

Forces screen orientation.

• Parameters: orientation (n=natural, l=left, r=right, u=upside down).

Returns the current UI hierarchy as an XML string. Useful for debugging layout.

Retrieves the message from a toast notification (transient popup).

• Parameters: wait_timeout.

Registers a watcher to automatically handle popups or specific text.

• Parameters: name, condition_text, action_text (what to click), click_action (bool).
• Example: qa.register_watcher("ANR", "Application not responding", "OK")

Removes specific or all registered watchers.