Automated UI Testing for HarmonyOS 5 Business Apps Using Python and hmdriver2

Believezj — Fri, 27 Jun 2025 09:10:06 +0000

As HarmonyOS 5 (a.k.a. Pure Harmony) continues to evolve, developers are increasingly exploring its testing ecosystem. In this post, I’ll walk you through an efficient automated UI testing solution for HarmonyOS 5 using the lightweight Python-based library hmdriver2. This guide covers framework selection, environment setup, and hands-on code examples to help you get started quickly.

1. Choosing the Right Testing Framework

HarmonyOS offers several tools for automated testing:

Tool	Description
`hdc`	Similar to Android’s `adb`, used for device connection, package management, and debugging.
`@ohos.UiTest`	Official HarmonyOS SDK module, similar to Android’s `uiautomator`. Requires writing tests in ArkTS and packaging them with the app.
`hypium`	Huawei's official automation framework. Feature-rich but heavy and complex to set up.
`hmdriver2`	Community-driven Python library with a simple syntax and easy setup for UI test automation.

While hypium is powerful, it requires more overhead. For quick iterations and lightweight UI automation, hmdriver2 is highly recommended.

📚 Docs:

GitHub Repo: hmdriver2
Video Tutorials: Search for "hmdriver2 HarmonyOS automation" on YouTube or Bilibili.

2. Environment Setup

2.1 Set Up HDC (Harmony Device Connector)

Download the HarmonyOS Command Line Tools
Locate the hdc binary (e.g., under command-line-tools/sdk/HarmonyOS-NEXT-DB2/openharmony/toolchains)
Add the following to your shell config (macOS example):

export HM_SDK_HOME="/Users/develop/command-line-tools/sdk/HarmonyOS-NEXT-DB2"
export PATH=$PATH:$HM_SDK_HOME/hms/toolchains:$HM_SDK_HOME/openharmony/toolchains
export HDC_SERVER_PORT=7035

Connect your phone via USB and enable "USB Debugging"
Run the command:

hdc list targets

You should see your device's serial number listed.

2.2 Install `hmdriver2`

pip3 install -U hmdriver2

To enable screen recording and image-based operations:

pip3 install -U "hmdriver2[opencv-python]"

Note: opencv-python is large, so it's not installed by default.

3. Writing Automated Tests

3.1 Launch an App

from hmdriver2.driver import Driver

d = Driver("FMR0223C13000076")  # Device serial number
d.start_app("com.anjuke.home", "EntryAbility")  # App bundle and ability name

3.2 Element Location Strategies

You can locate elements by various attributes such as:

id, key, text, type, description
clickable, longClickable, scrollable
enabled, focused, selected, checked, checkable
Relative positioning: isBefore, isAfter

Examples:

d(text="tab_recrod")
d(id="drag")
d(type="Button", index=0)
d(type="Button", text="tab_recrod")
d(text="showToast", isAfter=True)
d(id="drag", isBefore=True)

3.3 Interact with Elements and Retrieve Info

info = d(text="tab_recrod").info
print(info)

Sample output:

{
  "id": "",
  "type": "Button",
  "text": "tab_recrod",
  "isClickable": true,
  "bounds": {
    "left": 539, "top": 1282,
    "right": 832, "bottom": 1412
  },
  "boundsCenter": { "x": 685, "y": 1347 }
}

Interaction methods:

d(text="tab_recrod").click()
d(text="tab_recrod").click_if_exists()
d(text="tab_recrod").double_click()
d(text="tab_recrod").long_click()

# Drag one element to another
target = d(type="ListItem", index=1).find_component()
d(type="ListItem").drag_to(target)

# Pinch gestures
d(text="tab_recrod").pinch_in(scale=0.5)
d(text="tab_recrod").pinch_out(scale=2)

4. UI Tree Inspection with `uiviewer`

For easier element exploration, use the built-in viewer tool:

Installation:

pip3 install -U uiviewer

Run:

python3 -m uiviewer

Connect your device
Open the app screen
Click “Connect” to see the UI tree
Copy XPath or screen coordinates of components
Click “Dump Hierarchy” to refresh

5. Mini Demo Script

from hmdriver2.driver import Driver

d = Driver("FMR0223C13000076")
d.start_app("com.anjuke.home", "EntryAbility")

# Click on the “Rent” tab
d(text="Rent a house", index=0).click()

# Swipe down 5 times
for _ in range(5):
    d.swipe(0.5, 0.7, 0.5, 0.5, speed=2000)

# Return to home screen
d.go_home()

You can integrate this with pytest or unittest for test suite management and reporting.

6. Conclusion

hmdriver2 provides a simple yet powerful way to perform UI automation on HarmonyOS 5 devices using Python. Its lightweight nature makes it perfect for developers who want to write, debug, and run tests quickly without complex setup.

Whether you're testing a production HarmonyOS app or experimenting with Pure Harmony, this tool is worth adding to your toolkit.

DEV Community: Believezj