📖 中文文档

📝 About

HMDroidbot (HM stands for HarmonyOS, Droid stands for Android) is a lightweight test input generator for HarmonyOS (and Android). It forks from Droidbot and supports HarmonyOS NEXT devices. It can send random or scripted input events to test an HarmonyOS app, achieve higher code coverage more quickly, and generate a UI transition graph (UTG) after testing.

🥰 Awesome Features

💥 Support coverage report for HarmonyOS now! Including ability, page, etc. and some HarmonyOS-specific metrics! See the sample report below!

💥 Support both Android and HarmonyOS NEXT devices. Use the flag -is_harmonyos to specify the target system.

💥 Source code improvement. Easier to read and debug. Added typing to the source code and colorized the log. Use -debug flag to print the debug level log to the terminal!

💥 Use -log flag to get the hilog from the device. Check it in the report directory!

Prerequisite

1. Python 3.10+
2. HDC cmdtool 3.1.0a+

How to use

1. Make sure you have:

   • .hap file path of the app you want to analyze.

   We provided some sample hap for testing here.

   • A device or an emulator connected to your host machine via hdc. Use hdc list targets to checkout the connected device.

   • The SYSTEM variable is correctly chosen. See trouble shooting.

   • Install the required packages.

     Clone this repo and install with pip.

     1️⃣ (Optional) You can setup a virtual envirnment before installation. See venv module for details.

     In macOS or Linux:

     python3 -m venv droidenv
     source droidenv/bin/activate

     In Windows:

     python3 -m venv droidenv
     .\droidenv\Scripts\activate

     2️⃣ The following pip command will automatic grep and install the required packages for you.

     git clone https://github.com/XixianLiang/HMDroidbot.git
     cd HMDroidbot
     pip install -e .

     3️⃣ If successfully installed, you should be able to execute droidbot -h. (If failed to run droidbot cmd, try to use python3 -m droidbot.start -h instead).

2. Quick Start (Only available in WSL now):

   👋 Simply run the run_sample.sh file we provided to download the sample hap and try HMDroidbot!

   bash run_sample.sh

3. Start HMDroidbot:

   Run droidbot by python -m.

   python3 -m droidbot.start -a <absolute_path_to_hap> -o output_dir -is_harmonyos

   Run droidbot by droidbot

   droidbot -a <absolute_path_to_hap> -o output_dir -is_harmonyos

   Attention! -a is used to specify the path to hap, please use absolute path here! That's it! You will find much useful information, including the UTG, generated in the output dir.

   • If you are using multiple devices, you may need to use -t <device_serial> to specify the target device. The easiest way to determine a device's serial number is calling hdc list targets.
   • You may find the -debug tag useful while you are trying to debug the source code.
   • Use -log flag to get the hilog in HarmonyOS, which can be found in the report directory.
   • You may find other useful features in droidbot -h.

   Example Starting Scripts

   # Start by droidbot cmd
   droidbot -a <absolute_path_to_hap> -o output -t 23E**********1843 -count 1000 -is_harmonyos -debug
   
   # Start by running module. Easy to debug!
   # execute the following command in the HMDroidbot dir, which should include the setup.py.
   python -m droidbot.start -a <absolute_path_to_hap> -o output -t 23E**********1843 -count 1000 -is_harmonyos -debug

   vscode launch.json example

   

Trouble shooting

You should use the correct SYSTEM variable in droidbot/adapter/hdc.py.

We used WSL to develop this project. so the hdc tool we used in this project is actually hdc.exe by adding /mnt/.../hdc.exe on windows to the WSL PATH.

Due to HarmonyOS NEXT being in beta, the process of configuring the hdc environment is somewhat complex (especially on WSL). The overall idea for WSL configuration is to install the hdc tool on the host system and export the hdc.exe from the host system path through the WSL mnt path (since the phone is connected to the host system, this eliminates the need to configure USB port forwarding). If you encounter any issues while setting up the environment, please feel free to contact us.

📣 Info

Currently, HMDroidbot is maintained by 华东师范大学-移动软件分析与测试小组.

This project is led by Xixian Liang and Mengli Ming. We are supervised by Prof. Ting Su. Feel free to contact us if you have any questions or advices.

Join the QQ group (ID 904153331) to contact us and get the latest info.

Acknowledgement

• Droidbot
• awesome-hdc
• The development of this project receives generous help and advice from the HUAWEI engineers.

License

This project is based on the original MIT License (see LICENSE file) and includes my contributions, which are governed by Xixian Liang (see LICENSE_NEW file).