Automating HarmonyOS Apps with Appium: Setup, .hap Installation, Element Locating, and Log Retrieval

Appium is a powerful mobile automation testing tool; this article shows how to automate HarmonyOS (鸿蒙) applications using Appium, assuming readers have basic Android Appium experience.

Connection initialization differs slightly from Android; the following Python class sets desired capabilities and connects to the HarmonyOS device.

class BaseTests(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls.desired_caps = initDevices()
        uninstallApp(cls.desired_caps['udid'], cls.PACKAGE_NAME)
        installApp(cls.desired_caps['udid'], cls.apk_path)
        cls.desired_caps['appPackage'] = cls.PACKAGE_NAME
        cls.desired_caps['platformName'] = 'Android'
        cls.desired_caps['noReset'] = True
        cls.desired_caps['appActivity'] = 'MainAbilityShellActivity'   # dumpsys activity | grep -i run |grep 360
        cls.desired_caps['newCommandTimeout'] = "2000"
        cls.driver = webdriver.Remote('http://127.0.0.1:4723/wd/hub', cls.desired_caps)
        cls.driver.implicitly_wait(10)

Key capability values include PACKAGE_NAME (bundleName from the app's config.json), apk_path (path to the .hap file, noting Appium cannot install .hap directly), platformName set to "Android", appActivity set to the main ability, and other standard flags.

Since Appium cannot install .hap packages, the HDC (HarmonyOS Device Connector) command‑line tool is used. The script defines installApp and uninstallApp functions that invoke HDC commands.

def installApp(serialNum, packageName):
    try:
        if "Success" in subprocess.check_output("hdc -t {} app install  {}".format(serialNum, packageName), shell=True):
            print(u"安装成功")
            return True
        else:
            print(u"安装失败")
            return False
    except:
        print(u"安装失败")
        return False

def uninstallApp(serialNum, packageName):
    try:
        if "Success" in subprocess.check_output("hdc -t {} app uninstall  {}".format(serialNum, packageName)):
            print(u"卸载成功")
            return True
        else:
            print(u"未安装该应用")
    except:
        pass

Element location in HarmonyOS apps uses IDs directly, e.g., self.driver.find_element_by_id(id).click() and self.driver.find_element_by_id("Id_text_field").send_keys("hello123") . Name‑based locating, which was removed after Appium 1.5, can be re‑enabled by adding "name" to the locatorStrategies array in Appium's driver.js file.

this.locatorStrategies = ['xpath', 'id', 'class name', 'accessibility id', '-android uiautomator','name'];

After this change, elements can be found by name, e.g., self.driver.find_element_by_name("Flush").click() .

Log collection requires using HDC's hilog command, as Appium's driver.get_log('logcat') does not capture HarmonyOS logs. The following Python snippet runs hdc hilog and streams the output.

order = 'hdc hilog'
pi = subprocess.Popen(order, shell=True, stdout=subprocess.PIPE)
for i in iter(pi.stdout.readline, 'b'):
    print(i)

Other standard Appium actions such as self.driver.close_app() , self.driver.launch_app() , self.driver.hide_keyboard() , and self.driver.background_app(5) work as usual.

For compatibility testing on real devices that do not support .hap installation, remote device rental services (e.g., Huawei's test service) can be used to upload and install .hap packages without modifying certificates.

References to HarmonyOS developer resources are provided for further reading.