# HUI2
HUI2 is an advanced Android automation library that combines the power of uiautomator2 with OCR (Optical Character Recognition) capabilities. It provides developers and testers with an easy-to-use interface for Android app automation, testing, and interaction.
## 🚀 Features
- **OCR-based Text Recognition**: Find and interact with text elements that are not accessible through traditional UI automation
- **Android Device Control**: Full control over Android devices via ADB
- **Screenshot Analysis**: Capture and analyze screenshots for text recognition
- **Easy Text Clicking**: Click on text elements found via OCR
- **Text Waiting**: Wait for specific text to appear on screen using OCR or UI hierarchy
- **ADB Text Input**: Input text via ADB shell commands
- **Debug Mode**: Built-in debugging with visual OCR results
- **Flexible Text Matching**: Support for partial text matching and case-insensitive search
## 📦 Installation
```bash
pip install hui2
```
## 🔧 Prerequisites
- Python 3.8 or higher
- Android device with USB debugging enabled
- ADB (Android Debug Bridge) installed and accessible
## 🚀 Quick Start
### 1. Basic Setup
```python
from hui2 import HDevice
# Connect to device (replace with your device serial)
device = HDevice("your_device_serial", text_score=0.7, debug=True)
# Or connect via WiFi (replace with your IP:PORT)
device = HDevice("192.168.1.100:5555", text_score=0.7, debug=True)
```
### 2. Click Text via OCR
```python
# Click on text found via OCR
device.click_text_by_ocr("Login")
# If multiple instances of text exist, use index
device.click_text_by_ocr("Submit", index=0) # First instance
device.click_text_by_ocr("Submit", index=1) # Second instance
```
### 3. Wait for Text
```python
# Wait for text using OCR
if device.wait_text_by_ocr("Welcome", timeout=10):
print("Welcome text found!")
# Wait for text using UI hierarchy (faster, but limited)
if device.wait_text_by_hierarchy("Welcome", timeout=10):
print("Welcome text found in hierarchy!")
```
### 4. Text Input
```python
# Input text via ADB
device.input_text_by_adb("Hello World")
device.input_text_by_adb("Long text that will be split into chunks")
```
## 📚 Usage Examples
### Example 1: Social Media Automation (Instagram)
```python
from hui2 import HDevice
def automate_instagram_login(device, username, password):
"""Automate Instagram login flow"""
# Open Instagram app
device.shell("am start -n com.instagram.android/com.instagram.mainactivity.MainActivity")
# Wait for the app to load
device.wait_text_by_ocr("Log in", timeout=10)
# Enter username
device.input_text_by_adb(username)
# Click on password field (if accessible via OCR)
device.click_text_by_ocr("Password")
# Enter password
device.input_text_by_adb(password)
# Click login button
device.click_text_by_ocr("Log in")
# Wait for login confirmation
if device.wait_text_by_ocr("Home", timeout=15) or device.wait_text_by_ocr("Explore", timeout=15):
print("Login successful!")
return True
else:
print("Login failed!")
return False
# Usage
device = HDevice("your_device_serial")
automate_instagram_login(device, "your_username", "your_password")
```
### Example 2: E-commerce App Testing
```python
from hui2 import HDevice
def test_shopping_flow(device):
"""Test shopping flow in an e-commerce app"""
# Search for a product
device.click_text_by_ocr("Search")
device.input_text_by_adb("laptop")
# Click search button
device.click_text_by_ocr("Search")
# Wait for search results
device.wait_text_by_ocr("Results", timeout=10)
# Click on the first product
device.click_text_by_ocr("Add to Cart", index=0)
# Wait for confirmation
if device.wait_text_by_ocr("Added", timeout=5):
print("Product added to cart successfully!")
# Go to cart
device.click_text_by_ocr("Cart")
# Proceed to checkout
device.click_text_by_ocr("Checkout")
return True
# Usage
device = HDevice("your_device_serial")
test_shopping_flow(device)
```
### Example 3: Form Filling Automation
```python
from hui2 import HDevice
def fill_contact_form(device, name, email, message):
"""Automate contact form filling"""
# Fill name field
device.click_text_by_ocr("Name")
device.input_text_by_adb(name)
# Fill email field
device.click_text_by_ocr("Email")
device.input_text_by_adb(email)
# Fill message field
device.click_text_by_ocr("Message")
device.input_text_by_adb(message)
# Submit form
device.click_text_by_ocr("Submit")
# Wait for confirmation
if device.wait_text_by_ocr("Thank you", timeout=10):
print("Form submitted successfully!")
return True
else:
print("Form submission failed!")
return False
# Usage
device = HDevice("your_device_serial")
fill_contact_form(device, "John Doe", "john@example.com", "Hello, this is a test message.")
```
### Example 4: App Testing with Debug Mode
```python
from hui2 import HDevice
def test_app_with_debug(device_serial):
"""Test app with debug mode enabled for visual OCR results"""
# Initialize with debug mode enabled
device = HDevice(device_serial, ocr_debug=True)
# Navigate through app
device.click_text_by_ocr("Settings")
device.click_text_by_ocr("Profile")
device.click_text_by_ocr("Edit")
# Wait for text to appear
if device.wait_text_by_ocr("Edit Profile", timeout=5):
print("Edit profile screen loaded!")
# Fill form fields
device.input_text_by_adb("New Name")
device.input_text_by_adb("new@email.com")
# Save changes
device.click_text_by_ocr("Save")
# Check if changes were saved
if device.wait_text_by_ocr("Profile updated", timeout=5):
print("Profile updated successfully!")
# Debug images will be saved to ./vis_cache/ directory
print("Check ./vis_cache/ for OCR visualization images")
# Usage
test_app_with_debug("your_device_serial")
```
### Example 5: Multi-device Testing
```python
from hui2 import HDevice
import threading
def test_on_device(device_serial, test_name):
"""Run tests on a specific device"""
device = HDevice(device_serial)
print(f"Running {test_name} on {device_serial}")
# Your test logic here
device.click_text_by_ocr("Test")
device.wait_text_by_ocr("Success", timeout=10)
print(f"{test_name} completed on {device_serial}")
# Run tests on multiple devices simultaneously
def run_parallel_tests():
devices = ["device1_serial", "device2_serial", "device3_serial"]
test_name = "Basic Functionality Test"
threads = []
for device_serial in devices:
thread = threading.Thread(target=test_on_device, args=(device_serial, test_name))
threads.append(thread)
thread.start()
for thread in threads:
thread.join()
# Usage
run_parallel_tests()
```
## API Reference
### HDevice
Main class for Android device automation.
#### `__init__(device_serial, text_score=0.7, orc_debug=False)`
Initialize the device connection with OCR support.
- `device_serial`: Device serial number or WiFi address:port
- `text_score`: OCR recognition confidence threshold (0.0-1.0, default: 0.7)
- `ocr_debug`: Enable debug mode with visual output (default: False)
#### `click_text_by_ocr(text, index=0)`
Click on text found via OCR.
- `text`: Text to find and click
- `index`: Index of the text if multiple occurrences exist (default: 0)
- Returns: True if successful, False otherwise
#### `wait_text_by_ocr(text, timeout=10)`
Wait for text to appear on screen via OCR.
- `text`: Text to wait for
- `timeout`: Maximum wait time in seconds (default: 10)
- Returns: True if text found, False if timeout
#### `wait_text_by_hierarchy(text, stop_text=None, timeout=10)`
Wait for text using UI hierarchy (faster than OCR).
- `text`: Text to wait for
- `stop_text`: Stop condition text (optional)
- `timeout`: Maximum wait time in seconds (default: 10)
- Returns: True if text found, False if timeout or stop condition met
#### `input_text_by_adb(text, max_char=2)`
Input text via ADB shell.
- `text`: Text to input
- `max_char`: Maximum characters per input command (default: 2)
## OCR Configuration
- `text_score`: Higher values require more confidence in OCR results (0.7-0.9 recommended)
- `debug=True`: Saves OCR visualization images to `./vis_cache/` directory
## Use Cases
### App Testing
- Automated UI testing for Android apps
- Form filling and submission testing
- UI element verification
### Game Automation
- Clicking on game elements that aren't accessible via UI
- Automated gameplay sequences
### Data Extraction
- Extracting text from non-accessible UI elements
- Screenshot analysis and text extraction
### Accessibility Testing
- Testing apps for users with accessibility needs
- Verifying text visibility and readability
## Troubleshooting
### Common Issues
- **Device Not Found**: Ensure USB debugging is enabled and device is connected
- **OCR Not Working**: Try adjusting `text_score` value
- **Permission Errors**: Ensure ADB has proper permissions
### Debug Mode
Enable debug mode to save OCR visualization images:
```python
device = HDevice("your_serial", ocr_debug=True)
```
Visual results will be saved in `./vis_cache/` directory.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## License
MIT License - see the LICENSE file for details.
## Support
If you encounter any issues, please open an issue on the GitHub repository.
## About
HUI2 is built on top of:
- **uiautomator2** - Android UI automation
- **RapidOCR** - Fast OCR engine
- **OpenCV** - Computer vision library
Raw data
{
"_id": null,
"home_page": "https://github.com/h1code2/hui2",
"name": "hui2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "android automation ocr uiautomator2 testing",
"author": "h1code2",
"author_email": "h1code2@163.com",
"download_url": "https://files.pythonhosted.org/packages/fe/9b/18df220817393e69ca8aa84c84a4960652d2a089a38d99ad01bf7de56ea4/hui2-0.2.2.tar.gz",
"platform": null,
"description": "# HUI2\n\nHUI2 is an advanced Android automation library that combines the power of uiautomator2 with OCR (Optical Character Recognition) capabilities. It provides developers and testers with an easy-to-use interface for Android app automation, testing, and interaction.\n\n## \ud83d\ude80 Features\n\n- **OCR-based Text Recognition**: Find and interact with text elements that are not accessible through traditional UI automation\n- **Android Device Control**: Full control over Android devices via ADB\n- **Screenshot Analysis**: Capture and analyze screenshots for text recognition\n- **Easy Text Clicking**: Click on text elements found via OCR\n- **Text Waiting**: Wait for specific text to appear on screen using OCR or UI hierarchy\n- **ADB Text Input**: Input text via ADB shell commands\n- **Debug Mode**: Built-in debugging with visual OCR results\n- **Flexible Text Matching**: Support for partial text matching and case-insensitive search\n\n## \ud83d\udce6 Installation\n\n```bash\npip install hui2\n```\n\n## \ud83d\udd27 Prerequisites\n\n- Python 3.8 or higher\n- Android device with USB debugging enabled\n- ADB (Android Debug Bridge) installed and accessible\n\n## \ud83d\ude80 Quick Start\n\n### 1. Basic Setup\n\n```python\nfrom hui2 import HDevice\n\n# Connect to device (replace with your device serial)\ndevice = HDevice(\"your_device_serial\", text_score=0.7, debug=True)\n\n# Or connect via WiFi (replace with your IP:PORT)\ndevice = HDevice(\"192.168.1.100:5555\", text_score=0.7, debug=True)\n```\n\n### 2. Click Text via OCR\n\n```python\n# Click on text found via OCR\ndevice.click_text_by_ocr(\"Login\")\n\n# If multiple instances of text exist, use index\ndevice.click_text_by_ocr(\"Submit\", index=0) # First instance\ndevice.click_text_by_ocr(\"Submit\", index=1) # Second instance\n```\n\n### 3. Wait for Text\n\n```python\n# Wait for text using OCR\nif device.wait_text_by_ocr(\"Welcome\", timeout=10):\n print(\"Welcome text found!\")\n\n# Wait for text using UI hierarchy (faster, but limited)\nif device.wait_text_by_hierarchy(\"Welcome\", timeout=10):\n print(\"Welcome text found in hierarchy!\")\n```\n\n### 4. Text Input\n\n```python\n# Input text via ADB\ndevice.input_text_by_adb(\"Hello World\")\ndevice.input_text_by_adb(\"Long text that will be split into chunks\")\n```\n\n## \ud83d\udcda Usage Examples\n\n### Example 1: Social Media Automation (Instagram)\n\n```python\nfrom hui2 import HDevice\n\ndef automate_instagram_login(device, username, password):\n \"\"\"Automate Instagram login flow\"\"\"\n \n # Open Instagram app\n device.shell(\"am start -n com.instagram.android/com.instagram.mainactivity.MainActivity\")\n \n # Wait for the app to load\n device.wait_text_by_ocr(\"Log in\", timeout=10)\n \n # Enter username\n device.input_text_by_adb(username)\n \n # Click on password field (if accessible via OCR)\n device.click_text_by_ocr(\"Password\")\n \n # Enter password\n device.input_text_by_adb(password)\n \n # Click login button\n device.click_text_by_ocr(\"Log in\")\n \n # Wait for login confirmation\n if device.wait_text_by_ocr(\"Home\", timeout=15) or device.wait_text_by_ocr(\"Explore\", timeout=15):\n print(\"Login successful!\")\n return True\n else:\n print(\"Login failed!\")\n return False\n\n# Usage\ndevice = HDevice(\"your_device_serial\")\nautomate_instagram_login(device, \"your_username\", \"your_password\")\n```\n\n### Example 2: E-commerce App Testing\n\n```python\nfrom hui2 import HDevice\n\ndef test_shopping_flow(device):\n \"\"\"Test shopping flow in an e-commerce app\"\"\"\n \n # Search for a product\n device.click_text_by_ocr(\"Search\")\n device.input_text_by_adb(\"laptop\")\n \n # Click search button\n device.click_text_by_ocr(\"Search\")\n \n # Wait for search results\n device.wait_text_by_ocr(\"Results\", timeout=10)\n \n # Click on the first product\n device.click_text_by_ocr(\"Add to Cart\", index=0)\n \n # Wait for confirmation\n if device.wait_text_by_ocr(\"Added\", timeout=5):\n print(\"Product added to cart successfully!\")\n \n # Go to cart\n device.click_text_by_ocr(\"Cart\")\n \n # Proceed to checkout\n device.click_text_by_ocr(\"Checkout\")\n \n return True\n\n# Usage\ndevice = HDevice(\"your_device_serial\")\ntest_shopping_flow(device)\n```\n\n### Example 3: Form Filling Automation\n\n```python\nfrom hui2 import HDevice\n\ndef fill_contact_form(device, name, email, message):\n \"\"\"Automate contact form filling\"\"\"\n \n # Fill name field\n device.click_text_by_ocr(\"Name\")\n device.input_text_by_adb(name)\n \n # Fill email field\n device.click_text_by_ocr(\"Email\")\n device.input_text_by_adb(email)\n \n # Fill message field\n device.click_text_by_ocr(\"Message\")\n device.input_text_by_adb(message)\n \n # Submit form\n device.click_text_by_ocr(\"Submit\")\n \n # Wait for confirmation\n if device.wait_text_by_ocr(\"Thank you\", timeout=10):\n print(\"Form submitted successfully!\")\n return True\n else:\n print(\"Form submission failed!\")\n return False\n\n# Usage\ndevice = HDevice(\"your_device_serial\")\nfill_contact_form(device, \"John Doe\", \"john@example.com\", \"Hello, this is a test message.\")\n```\n\n### Example 4: App Testing with Debug Mode\n\n```python\nfrom hui2 import HDevice\n\ndef test_app_with_debug(device_serial):\n \"\"\"Test app with debug mode enabled for visual OCR results\"\"\"\n \n # Initialize with debug mode enabled\n device = HDevice(device_serial, ocr_debug=True)\n \n # Navigate through app\n device.click_text_by_ocr(\"Settings\")\n device.click_text_by_ocr(\"Profile\")\n device.click_text_by_ocr(\"Edit\")\n \n # Wait for text to appear\n if device.wait_text_by_ocr(\"Edit Profile\", timeout=5):\n print(\"Edit profile screen loaded!\")\n \n # Fill form fields\n device.input_text_by_adb(\"New Name\")\n device.input_text_by_adb(\"new@email.com\")\n \n # Save changes\n device.click_text_by_ocr(\"Save\")\n \n # Check if changes were saved\n if device.wait_text_by_ocr(\"Profile updated\", timeout=5):\n print(\"Profile updated successfully!\")\n \n # Debug images will be saved to ./vis_cache/ directory\n print(\"Check ./vis_cache/ for OCR visualization images\")\n\n# Usage\ntest_app_with_debug(\"your_device_serial\")\n```\n\n### Example 5: Multi-device Testing\n\n```python\nfrom hui2 import HDevice\nimport threading\n\ndef test_on_device(device_serial, test_name):\n \"\"\"Run tests on a specific device\"\"\"\n device = HDevice(device_serial)\n \n print(f\"Running {test_name} on {device_serial}\")\n \n # Your test logic here\n device.click_text_by_ocr(\"Test\")\n device.wait_text_by_ocr(\"Success\", timeout=10)\n \n print(f\"{test_name} completed on {device_serial}\")\n\n# Run tests on multiple devices simultaneously\ndef run_parallel_tests():\n devices = [\"device1_serial\", \"device2_serial\", \"device3_serial\"]\n test_name = \"Basic Functionality Test\"\n \n threads = []\n for device_serial in devices:\n thread = threading.Thread(target=test_on_device, args=(device_serial, test_name))\n threads.append(thread)\n thread.start()\n \n for thread in threads:\n thread.join()\n\n# Usage\nrun_parallel_tests()\n```\n\n## API Reference\n\n### HDevice\n\nMain class for Android device automation.\n\n#### `__init__(device_serial, text_score=0.7, orc_debug=False)`\n\nInitialize the device connection with OCR support.\n\n- `device_serial`: Device serial number or WiFi address:port\n- `text_score`: OCR recognition confidence threshold (0.0-1.0, default: 0.7)\n- `ocr_debug`: Enable debug mode with visual output (default: False)\n\n#### `click_text_by_ocr(text, index=0)`\n\nClick on text found via OCR.\n\n- `text`: Text to find and click\n- `index`: Index of the text if multiple occurrences exist (default: 0)\n- Returns: True if successful, False otherwise\n\n#### `wait_text_by_ocr(text, timeout=10)`\n\nWait for text to appear on screen via OCR.\n\n- `text`: Text to wait for\n- `timeout`: Maximum wait time in seconds (default: 10)\n- Returns: True if text found, False if timeout\n\n#### `wait_text_by_hierarchy(text, stop_text=None, timeout=10)`\n\nWait for text using UI hierarchy (faster than OCR).\n\n- `text`: Text to wait for\n- `stop_text`: Stop condition text (optional)\n- `timeout`: Maximum wait time in seconds (default: 10)\n- Returns: True if text found, False if timeout or stop condition met\n\n#### `input_text_by_adb(text, max_char=2)`\n\nInput text via ADB shell.\n\n- `text`: Text to input\n- `max_char`: Maximum characters per input command (default: 2)\n\n## OCR Configuration\n\n- `text_score`: Higher values require more confidence in OCR results (0.7-0.9 recommended)\n- `debug=True`: Saves OCR visualization images to `./vis_cache/` directory\n\n## Use Cases\n\n### App Testing\n- Automated UI testing for Android apps\n- Form filling and submission testing\n- UI element verification\n\n### Game Automation\n- Clicking on game elements that aren't accessible via UI\n- Automated gameplay sequences\n\n### Data Extraction\n- Extracting text from non-accessible UI elements\n- Screenshot analysis and text extraction\n\n### Accessibility Testing\n- Testing apps for users with accessibility needs\n- Verifying text visibility and readability\n\n## Troubleshooting\n\n### Common Issues\n- **Device Not Found**: Ensure USB debugging is enabled and device is connected\n- **OCR Not Working**: Try adjusting `text_score` value\n- **Permission Errors**: Ensure ADB has proper permissions\n\n### Debug Mode\n\nEnable debug mode to save OCR visualization images:\n\n```python\ndevice = HDevice(\"your_serial\", ocr_debug=True)\n```\n\nVisual results will be saved in `./vis_cache/` directory.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nMIT License - see the LICENSE file for details.\n\n## Support\n\nIf you encounter any issues, please open an issue on the GitHub repository.\n\n## About\n\nHUI2 is built on top of:\n\n- **uiautomator2** - Android UI automation\n- **RapidOCR** - Fast OCR engine\n- **OpenCV** - Computer vision library\n",
"bugtrack_url": null,
"license": null,
"summary": "Android automation library with OCR support based on uiautomator2",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/h1code2/hui2"
},
"split_keywords": [
"android",
"automation",
"ocr",
"uiautomator2",
"testing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "216684c9959f65602c5a67baba4a9c638ec0cc5b8d860338cc85303b01019fb7",
"md5": "c5832582ca8a11d349c09e0cb1125ec0",
"sha256": "107f21074d6ed70aeef0c1d7741f61856d9d8e6b9de2f0469b8d9525eb948183"
},
"downloads": -1,
"filename": "hui2-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5832582ca8a11d349c09e0cb1125ec0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7581,
"upload_time": "2025-10-23T07:22:44",
"upload_time_iso_8601": "2025-10-23T07:22:44.213168Z",
"url": "https://files.pythonhosted.org/packages/21/66/84c9959f65602c5a67baba4a9c638ec0cc5b8d860338cc85303b01019fb7/hui2-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "fe9b18df220817393e69ca8aa84c84a4960652d2a089a38d99ad01bf7de56ea4",
"md5": "5158129e1c1aeff0f8cf19afe92ccd04",
"sha256": "68507cdfd01cb38968717b6522de0d1a7d8b2a653e0a67e417e0b10886e4ac91"
},
"downloads": -1,
"filename": "hui2-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "5158129e1c1aeff0f8cf19afe92ccd04",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8147,
"upload_time": "2025-10-23T07:22:46",
"upload_time_iso_8601": "2025-10-23T07:22:46.269131Z",
"url": "https://files.pythonhosted.org/packages/fe/9b/18df220817393e69ca8aa84c84a4960652d2a089a38d99ad01bf7de56ea4/hui2-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 07:22:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "h1code2",
"github_project": "hui2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hui2"
}
JSON
