HACMony is an LLM-based mobile application automation testing tool that supports intelligent application exploration and detecting Hopping-related Audio-stream Conflict (HAC) Issues.
- Hopping-related Audio-stream Conflict Issues detecting
- LLM-based intelligent GUI exploration
- Support for multiple operating systems: Android and HarmonyOS
- Automatic generation of window transition graphs (WTG)
- Python 3.9
- LLM API key
- ADB tools for Android devices
- HDC tools for HarmonyOS devices
- Clone the repository
git clone <repository-url>
cd hacmony- Install dependencies
pip install -r requirements.txt- Install ADB and HDC tools
# Install using Homebrew
brew install android-platform-tools- Download Android SDK Platform Tools
- Extract the downloaded zip file
- Add the extracted folder path to the system environment variable PATH
# Ubuntu/Debian
sudo apt-get install android-tools-adb
# Fedora
sudo dnf install android-tools- Download DevEco Studio
- Install DevEco Studio, which will automatically install HDC tools
- Alternatively, you can download the HDC toolkit separately
# Verify ADB installation
adb version
# Verify HDC installation
hdc version- Configure LLM Parameters
Create and edit the .env file in the project directory:
touch .envPlease copy the LLM configuration sample below to the .env file and modify it with your own API information:
BASE_URL="https://api.openai.com/v1"
MODEL="gpt-4-turbo"
API_KEY="YOUR_API_KEY"
# List all HarmonyOS devices
python run.py devices --os harmony
# List all Android devices
python run.py devices --os androidUse LLM for application exploration:
python run.py explore --os <operating_system> -p <app_path> -s <device_port> --testcase <script_path> | --hardware <hardware_kind> [options]Parameter description:
--os: [Required] Specify the operating system type (android or harmony)-p, --app_path: [Required] Specify the path to the APK or HAP file of the application-s, --serial: [Required] Specify the device port number(s), multiple devices can be specified, e.g.,-s emulator-5554 emulator-5556-m, --max_steps: [Optional] Specify the maximum number of exploration steps, default is 20-o, --output: [Optional] Specify the output directory, default is "output/"
You must specify one of the following exploration types: [Required]
--testcase: Specify test script file paths for exploration, multiple paths can be specified, e.g.,--testcase test1.py test2.py--hardware: Specify hardware resources to test, multiple resources can be specified, e.g.,--hardware audio camera
python run.py detect --os <operating_system> --hardware <hardware_type> -wp <wtg_path> -op <other_wtg_path> -sd <source_device> -td <target_device>Parameter description:
--os: [Required] Specify the operating system type (android or harmony)--hardware: [Required] Specify hardware resources to test (audio, microphone, camera, keyboard)-wp, --wtg_path: [Required] Specify the test wtg path for enhancement and detection-op, --other_wtg_path: [Required] Specify other wtg path for enhancement, multiple paths can be specified-sd, --source_device: [Required] Specify the source device serial for detection-td, --target_device: [Required] Specify the target device serial for detection
- Test the speaker functionality of a HarmonyOS application:
python run.py explore --os harmony -p path/to/app.hap -s 127.0.0.1:5555 --hardware audio- Explore audio and camera functionality of an Android application:
python run.py explore --os android -p path/to/app.apk -s emulator-5554 --hardware audio camera- Explore an Android application using test scripts:
python run.py explore --os android -p path/to/app.apk -s emulator-5554 --testcase path/to/test_script1.py path/to/test_script2.py- Specify maximum exploration steps and output directory:
python run.py explore --os android -p path/to/app.apk -s emulator-5554 --hardware audio -m 30 -o results/After exploration is complete, the results will be saved in the specified output directory, including:
- Window Transition Graph (WTG): Records the UI states and transitions of the application
- Screenshots: Screenshots of each UI state
- UI Widget Tree: Widget tree of each UI state