Metadata-Version: 2.4
Name: qa_automation2
Version: 2.0.1
Summary: Automation test for phone
Author-email: Thoang <nhothoang@gmail.com>
License: GPL-3.0-only
Project-URL: Documentation, https://github.com/NhoThoang/QA_Automation2.git/README.md
Project-URL: Source, https://github.com/NhoThoang/QA_Automation2.git
Project-URL: Tracker, https://github.com/NhoThoang/QA_Automation2.git/issues
Description-Content-Type: text/markdown
Requires-Dist: uiautomator2>=3.2.8
Requires-Dist: adbutils

# QA Automation Core Documentation

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.

## Initialization

```python
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")
```

## Core Functions

### 1. Element Interaction

#### `Find_element`
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`.

#### `Find_elements`
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.

#### `wait_for_element`
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`.

#### `wait_element_gone`
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`.

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

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

#### `Touch`
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.

#### `send_text`
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`).

#### `click_element_relative`
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")`

#### `click_child_element`
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).

### 2. Scroll & Search

#### `scroll`
Performs a simple scroll gesture.

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

#### `scroll_to_find_element`
Scrolls in a specified direction until the element is found.

*   **Parameters:** Element identifiers plus `type_scroll`, `max_scrolls`.

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

### 3. Device Control

#### `press_key`
Simulates a physical key press.

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

#### `manage_screen`
Controls the device screen state.

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

#### `zoom_screen`
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.

### 4. App & System

#### `start_app` / `stop_app`
Starts or stops an application by package name.

#### `clear_app_data`
Clears the cache and data of an application (like a fresh reinstall).
*   **Parameters:** `package_name`.

#### `get_current_app`
Retrieves information about the currently running app and activity on the screen.
*   **Returns:** A dictionary with `package` and `activity` keys.

#### `install_app` / `uninstall_app`
Installs an app from a local APK path or uninstalls it by package name.

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

#### `abd_shell`
Executes an ADB shell command on the device.

### 5. Information Retrieval

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

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

### 6. Advanced Gestures & Interactions

#### `drag_element`
Drags an element to another element or specific coordinates.
*   **Parameters:** `source_name`, `dest_name` (or `dest_x`, `dest_y`), `duration`.

#### `double_click`
Double clicks on an element.
*   **Parameters:** `name`, `type_`.

#### `touch_action`
Performs raw pointer/touch actions at specific screen coordinates.
*   **Parameters:** `action` (`down`, `move`, `up`), `x`, `y`.

#### `swipe`
Performs a direct coordinate-to-coordinate swipe gesture.
*   **Parameters:** `fx`, `fy` (from), `tx`, `ty` (to), `duration`.

### 7. System Operations

#### `capture_screenshot`
Captures a screenshot and saves it to a file on your PC.
*   **Parameters:** `filename` (Absolute or relative path).

#### `start_recording` / `stop_recording`
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.

#### `push_file` / `pull_file`
Transfers files between the PC and the connected Android device.
*   **Parameters:** `pc_path`, `device_path`.

#### `open_system_ui`
Opens system panels.
*   **Parameters:** `target` (`notification`, `quick_settings`).

#### `set_clipboard` / `get_clipboard`
Sets or retrieves text from the device clipboard.

#### `rotate_screen`
Forces screen orientation.
*   **Parameters:** `orientation` (`n`=natural, `l`=left, `r`=right, `u`=upside down).

### 8. Debug & Watchers

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

#### `get_toast`
Retrieves the message from a toast notification (transient popup).
*   **Parameters:** `wait_timeout`.

#### `register_watcher`
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")`

#### `remove_watcher` / `remove_all_watchers`
Removes specific or all registered watchers.
