DEV Community

Believezj
Believezj

Posted on

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

#harmonyos5

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
Enter fullscreen mode Exit fullscreen mode
  • Connect your phone via USB and enable "USB Debugging"
  • Run the command: 
hdc list targets
Enter fullscreen mode Exit fullscreen mode

You should see your device's serial number listed.

2.2 Install hmdriver2 

pip3 install -U hmdriver2
Enter fullscreen mode Exit fullscreen mode

To enable screen recording and image-based operations:

pip3 install -U "hmdriver2[opencv-python]"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

3.3 Interact with Elements and Retrieve Info 

info = d(text="tab_recrod").info
print(info)
Enter fullscreen mode Exit fullscreen mode

Sample output:

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

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)
Enter fullscreen mode Exit fullscreen mode

4. UI Tree Inspection with uiviewer

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

Installation: 

pip3 install -U uiviewer
Enter fullscreen mode Exit fullscreen mode

Run: 

python3 -m uiviewer
Enter fullscreen mode Exit fullscreen mode
  • 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()
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)