最近团队分到一个任务要把自动化脚本从Android设备迁移到鸿蒙手机上跑。原本以为和普通安卓一样结果真动起手来Appium连接鸿蒙这台设备就折腾了大半天。网上关于“appium鸿蒙”的资料很杂不是讲得太浅就是照搬安卓配置真正能把环境从零搭通、能稳定跑起来的文章很少。这篇就把我实测下来的环境配置全过程整理出来从JDK到Node、从Appium 2.x到UiAutomator2驱动再到鸿蒙手机的开发者选项和adb连接每一步都有截图级的解释和踩坑提醒希望能帮到正在搭环境的朋友。我默认你是有一定自动化测试基础、手里正好有一台鸿蒙手机或者正在为团队做设备选型。这篇文章不聊抽象概念只讲“怎么把环境搭起来并且真的跑出一个脚本”。1. 先把思路理清楚鸿蒙手机为什么能跑Appium以及怎么选型1.1 鸿蒙系统与Android的兼容关系很多新手看到“鸿蒙”两个字就懵了觉得这是个完全陌生的系统Appium这套安卓工具链肯定用不了。其实这里要分清楚两个阶段。早期鸿蒙HarmonyOS 1.0到4.x是基于开源代码做了深度定制的系统底层依然是Android兼容架构因此能够直接安装和运行APK应用。Appium通过UiAutomator2驱动去调用系统层的自动化接口在鸿蒙手机上一样可以工作。这也是目前大多数做鸿蒙自动化测试团队的现状手里拿的是鸿蒙4.2或者4.4的手机但被测应用还是Android APK包。从鸿蒙NEXT纯血鸿蒙开始情况就不一样了系统不再兼容Android应用只能跑HAP格式的原生鸿蒙应用。Appium默认的UiAutomator2驱动在这个阶段已经失效想测纯血鸿蒙应用需要走华为官方推荐的DevEco Testing或者基于OpenHarmony的测试框架路线Appium想要继续用在NEXT设备上就得等社区适配或者自己折腾服务端扩展。所以这篇文章先说清楚一个前提我整理的环境配置方案主要针对鸿蒙4.x及更早版本也就是可以安装运行APK的鸿蒙手机。如果你手里是NEXT设备配置思路会有根本差异后面我会单独说明。1.2 自动化方案选型三条路怎么选接触鸿蒙自动化测试后会发现市面上其实有三条技术路线很多人一开始就选错了导致越走越偏。传统Appium UiAutomator2这是最成熟、上手最快的方式适合存量鸿蒙手机兼容APK资源多、社区成熟脚本可以复用原有Android用例。缺点是依赖系统里还留着Android兼容层。华为DevEco Testing unicorn测试框架这是华为官方针对鸿蒙原生应用推出的测试框架适配HarmonyOS NEXT可以测试HAP应用。功能很全但生态较新使用时要适应华为的IDE体系。Appium插件化扩展Appium 2.x支持通过插件机制扩展驱动社区里有针对鸿蒙的驱动方案出现但成熟度、文档完整度还不足以支撑大规模商用。我这篇文章核心讲第一条路的完整环境配置。为什么选它因为根据我得到的任务被测App还是APK包而且脚本资产都在Appium里迁移成本最低。如果你是新项目、原生鸿蒙应用那请直接考虑第二条路线别在Appium上花太多时间。2. 环境配置全流程从JDK到鸿蒙手机连接2.1 安装JDK与Node.js版本选择Appium的底层运行机制需要几步协作Node.js负责跑Appium服务器Java负责驱动UiAutomator2做中间通讯Android SDK用于设备连接和构建测试桩。这三样东西是Appium运行的底座版本选错后面就是无止境的报错。先看JDK。Appium 2.x要求Java 8以上但我在实际使用中强烈建议装JDK 11或者JDK 17因为版本更高的JDK在apk signing、系统兼容性上问题更少。我之前在一台Windows机器上装了JDK 8跑Appium启动session时报了Java安全证书的错折腾很久换成JDK 17后一切正常。安装步骤不再赘述但要检查环境变量是否正确java -version javac -version echo %JAVA_HOME%我在实操中发现很多人装了JDK但系统里还残留着JRE的环境变量路径导致Appium调用的Java版本不对。建议在系统环境变量里把JAVA_HOME单独指到JDK的安装目录并把%JAVA_HOME%\bin移到Path最前面。接着是Node.js。Appium本身是一个Node.js应用所以Node环境是它的宿主。这里要记住一个经验不要追新不要用奇奇怪怪的测试版装官方LTS版本就好。我用的还是Node 18稳定得一批Node 20也试过没问题。装完之后检查node -v npm -v国内网络环境下npm官方源下载速度很折磨人建议提前配置淘宝镜像。这一步看似简单却能让后面安装Appium的效率提升十倍npm config set registry https://registry.npmmirror.com2.2 安装Appium服务端与UiAutomator2驱动Appium 2.x和Appium 1.x最大的区别在于驱动和插件被拆分了。1.x时代装一个Appium就自带所有能力2.x变成驱动独立管理有些朋友安装完Appium 2.x后直接启动发现不认识设备就是因为驱动没装。全局安装Appiumnpm install -g appium安装完成后验证appium --version我实测安装的是2.x版本这一步通常很快。接下来安装UiAutomator2驱动appium driver install uiautomator2注意这一步可能要等上一段时间因为驱动包里包含了不少依赖。如果你看到进度条卡住或者报ECONNRETRY之类的错误大概率还是网络问题。这时候用镜像GitHub地址或者手动下载驱动包后本地安装都是可行的。我的实战经验是先用appium driver list --installed看看当前装了哪些驱动确认uiautomator2出现在列表里再继续。2.3 Android SDK与adb配置即使你是测鸿蒙手机底层走的是Android兼容层所以还是绕不开Android SDK。Appium启动时需要通过adb连接设备、安装bootstrap、执行shell命令这些全靠SDK里的platform-tools。首先下载Android SDK命令行工具创建一个干净的SDK目录然后用sdkmanager装上platform-tools和build-toolssdkmanager platform-tools platforms;android-30 build-tools;30.0.3安装完成后配置环境变量。这里要格外注意很多人只配了PATH忘了ANDROID_HOME这个变量。Appium 2.x查找SDK路径时两个缺一不可ANDROID_HOMED:\Android\sdk Path追加 %ANDROID_HOME%\platform-tools Path追加 %ANDROID_HOME%\build-tools\30.0.3配置完成后在命令行验证adb version adb devices如果此时已经用USB线把鸿蒙手机连到电脑上adb devices里能看到设备序列号就说明连接正常。序列号可能是正常的字母数字串也可能像HAUA-...这种带厂商标志的格式都是正常的。2.4 鸿蒙手机侧的开发者模式与USB调试设置这部分是整个过程中最容易让新手卡住的一环。鸿蒙手机虽然整体逻辑和安卓相似但在开发者选项里藏了不少特殊开关少开一个就连接不上。打开方式在鸿蒙手机里连点版本号七次开启开发者模式随后在设置里能搜索到“开发人员选项”。进到开发者选项后需要重点确认以下几个开关USB调试这是基础的调试入口必须打开。“仅充电模式下允许ADB调试”这个开关相当关键鸿蒙手机默认在仅充电模式下不允许ADB调试如果你连接电脑后选的传输方式不对adb就会一直识别不到设备。“无线调试”如果你打算用WiFi连接代替USB线要打开这个并且需要用adb pair进行配对。“监控ADB安装应用”建议打开否则部分Appium自动安装测试桩的操作会失败。一个容易被忽略的细节有些鸿蒙手机连接电脑后会弹窗询问“是否允许USB调试”这个弹窗只会出现一次如果你手快点掉了“取消”后续怎么插拔都无法再唤起需要在开发者选项里“撤销USB调试授权”后重新插拔。我在配置过程中深刻体会到鸿蒙设备的USB调试授权机制和原生Android不完全一样它更加保守默认很多权限都是关闭的。耐心检查每一项开关比反复重装驱动更有用。3. 关键配置环节Appium Inspector与Desired Capabilities3.1 Appium Inspector连接鸿蒙设备的完整配置环境装好、设备识别到之后下一步就是用Appium Inspector来检查元素。这一步相当于给手机做“内窥镜”能看到界面上的控件树和属性是后面写定位表达式的基础。Appium Inspector在2.x时代是独立安装的桌面工具下载安装后界面上需要填三块内容Remote Host、Remote Port、Desired Capabilities。我的配置如下{ platformName: Android, appium:automationName: UiAutomator2, appium:udid: 你的设备序列号, appium:deviceName: 任意名称可以填设备型号, appium:appPackage: com.huawei.android.dialer, appium:appActivity: .Dialer, appium:noReset: true, appium:newCommandTimeout: 600 }这里用华为拨号应用来举例因为这个App在每台鸿蒙手机上都有适合验证环境。如果你要测自己的应用把appPackage和appActivity换成实际值就行。点击“Start Session”Appium会启动一个session然后往手机上推送测试相关组件大概等20秒左右就能看到界面快照。如果你在这一步看到“An unknown server-side error occurred while processing the command”不要慌大概率是设备连接或者驱动问题我会在第五部分汇总排查方法。3.2 Desired Capabilities参数逐项详解Desired Capabilities是Appium的“接头暗号”告诉服务器这次会话要测什么设备、什么平台、什么应用。很多人在官网文档里看过这些参数但不知道每个参数在鸿蒙设备上到底起什么作用。这里我结合实践逐项拆一下重要参数。platformName最基础填Android。鸿蒙4.x兼容层会认为自己就是Android所以这里不要填写其他值。appium:automationName自动化引擎必须填UiAutomator2。Appium 2.x如果没有显式指定会自动选一个驱动但为了避免歧义最好写清楚。appium:udid设备唯一标识。如果电脑连着两台设备这个字段就是用来区分目标的。可以通过adb devices查看。appium:appPackage和应用Activity你要启动的应用包名和入口页面相当于告诉Appium“把车开到哪个停车场、从哪个门进去”。appium:noReset是否不重置应用数据。实测跑鸿蒙上的应用这个建议改成true否则每次session启动时可能会把应用缓存清掉导致登录态丢失。appium:newCommandTimeout会话空闲多久后自动关闭单位是秒。调试期间建议设大一点免得想半天定位表达式的时候session自己断了。appium:unicodeKeyboard和appium:resetKeyboard如果输入框需要输入中文这两个参数建议设置前者使用Appium自带的Unicode输入法后者测试结束后重置输入法避免把用户手机上输入法搞乱。appium:systemPortUiAutomator2在手机上通讯用的端口多设备并行测试时必须手动指定为不同的值。我在多次调试中意识到这些参数不仅是“填对就行”的问题更能在调试阶段帮你迅速定位瓶颈。比如连不上设备时我会先单测udid是否正确打开应用失败时我会只测appPackage和appActivity两个值用adb命令验证再回填。3.3 连接时的常见报错与初次点击操作第一次用Inspector连接鸿蒙设备时我最常遇到的问题是“Could not find a driver for automationName UiAutomator2”。这个报错在Appium 2.x里尤其常见原因很简单驱动没有安装成功或者安装到了另一个Appium实例下。排查方式appium driver list --installed如果列表里是空的重新执行安装命令。如果列表里已经存在但依然报错可能是环境变量指向了不同版本的Appium用where appium看看实际调用的是哪个路径。连接成功后Inspector会展示两个面板左边是屏幕截图右边是控件树。点击任意控件下方会显示该控件的resource-id、class、text、content-desc等属性这些就是编写定位表达式的重要依据。在鸿蒙设备上有个特点和原生Android不太一样部分鸿蒙组件的属性值可能是空的尤其text和content-desc不一定会填充这个时候就要靠resource-id或者xpath来兜底。同时鸿蒙界面的控件层级往往比原生Android更深用绝对路径写xpath的效率极低我一般只取关键属性组合尽量不依赖层级。4. 跑通第一个自动化脚本从启动应用到断言4.1 用Python写一个最小Demo脚本Inspector连接正常后接下来就可以脱离图形界面写一段最小脚本验证整个链路。我用的是Python因为团队技术栈主要用这个Appium的Python客户端库也维护得很好。先安装依赖pip install Appium-Python-Client注意这里装的是Appium的客户端库不是Appium服务端。很多人会搞混以为是同一个东西。服务端负责和设备交互客户端库负责让你的代码能跟服务端对话。写一个最小示例from appium import webdriver caps { platformName: Android, appium:automationName: UiAutomator2, appium:udid: 你的设备序列号, appium:appPackage: com.huawei.android.dialer, appium:appActivity: .Dialer, appium:noReset: True, appium:newCommandTimeout: 600, } driver webdriver.Remote(http://127.0.0.1:4723/wd/hub, caps) print(连接成功当前页面标题, driver.current_package) driver.quit()在运行这个脚本之前要先把Appium服务端启动起来。启动方式很简单appium更规范一点还可以指定监听地址appium -p 4723 -a 127.0.0.1脚本执行后如果终端打印出当前包名就说明Appium已经成功驱动鸿蒙手机环境配置这一步就算大功告成了。4.2 元素定位与中文输入的几个实战细节跑通session之后写用例就是水到渠成的事。但我在鸿蒙手机上实操明显感觉到比原生Android多了一些工作。第一点元素定位优先级。在鸿蒙4.x系统中resource-id普遍存在且稳定优先用find_element_by_id。如果id重复或者没有再考虑text属性但鸿蒙部分系统应用存在“自适应UI”同一控件在不同分辨率下text可能会变化使用contains匹配会比精确完全匹配更稳。第二点中文输入。鸿蒙手机的自带输入法有时候不受Appium控制表现为send_keys传了中文却打不进去。我的经验是配合前面提到的两个capabilitiescaps[appium:unicodeKeyboard] True caps[appium:resetKeyboard] True如果还是不行可能是输入框没有聚焦先用driver.click_element点一下输入框再执行输入。第三点等待策略。鸿蒙应用页面渲染速度有时候比原生Android慢尤其第一次冷启动时应用在系统层有额外的权限弹窗或隐私协议确认。我通常建议使用WebDriverWait设置10秒以上的等待而不是用固定sleepfrom appium.webdriver.common.appiumby import AppiumBy from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC wait WebDriverWait(driver, 10) el wait.until(EC.presence_of_element_located((AppiumBy.ID, com.huawei.android.dialer:id/xxx)))4.3 完整脚本示例自动打开拨号盘并输入号码为了让你能直接“抄作业”我贴一个我在鸿蒙手机上实测通过的脚本。功能很简单打开拨号应用点击键盘上的数字然后清除。import time from appium import webdriver from appium.webdriver.common.appiumby import AppiumBy caps { platformName: Android, appium:automationName: UiAutomator2, appium:udid: 你的设备序列号, appium:appPackage: com.huawei.android.dialer, appium:appActivity: .Dialer, appium:noReset: True, appium:unicodeKeyboard: True, appium:resetKeyboard: True, } driver webdriver.Remote(http://127.0.0.1:4723/wd/hub, caps) time.sleep(3) # 点击底部拨号键盘Tab tab driver.find_element(AppiumBy.ID, com.huawei.android.dialer:id/contactTab) tab.click() time.sleep(1) # 模拟点击数字1 digit_one driver.find_element(AppiumBy.ID, com.huawei.android.dialer:id/dial_one) digit_one.click() # 输入电话号码 num_field driver.find_element(AppiumBy.ID, com.huawei.android.dialer:id/dial_edit_text) num_field.clear() num_field.send_keys(10086) print(输入完成当前文本, num_field.text) driver.quit()这个脚本我反复跑过多次稳定通过。如果你的鸿蒙系统版本较新控件id命名可能不同先用Inspector确认一下。5. 常见问题与排查技巧实录5.1 设备连接与权限问题速查表这节内容来自我搭建环境和帮同事排错的真实记录做成表格方便快速对照。现象原因解决办法adb devices 看不到设备USB调试未开启/未授权打开开发者选项中的USB调试重新插拔数据线授权弹窗必须点允许adb显示设备状态为unauthorized设备端未确认授权手机屏幕上会弹出授权框点击“允许”若弹窗已消失到开发者选项里撤销授权后重试Appium连接时提示no devices found多设备时未指定udidadb devices查序列号在capabilities里填udid鸿蒙手机连接后频繁断开USB数据线质量差或供电不足换原装线换电脑USB口避免用前置接口Inspector连接失败提示Could not find a driverUiAutomator2驱动未安装appium driver install uiautomator2安装后appium driver list确认我在实际操作中的一个体会是多数连接问题不是由于Appium服务端坏了而是手机侧的小开关没开对或者授权被误取消。排查顺序建议是先看adb devices再看USB调试模式最后才去动Appium配置。5.2 驱动安装与启动问题处理Appium服务端经常遇到的几个坑我也在这里汇总一下。第一个坑appium driver install uiautomator2下载卡在99%。原因大概率是网络问题因为驱动发布包都在GitHub上。我的处理方法是配置代理或者使用npm镜像加速实在不行就手动下载驱动包然后本地安装appium driver install --sourcelocal /path/to/uiautomator2.zip第二个坑启动Appium后一切正常但运行脚本报Error: socket hang up。这通常是Appium服务端进程在session建立过程中崩溃了可以查看Appium终端输出常见原因是Java版本太旧或者Node版本不兼容。解决方法是升级到JDK 17和Node 18以上然后完全重启Appium。第三个坑端口占用。Appium默认监听4723端口如果之前有异常退出的Appium进程没有释放端口启动会失败。查看和清理方式netstat -ano | findstr 4723 taskkill /PID 你的进程号 /F5.3 元素定位与测试稳定性的经验心得最后一个部分分享一些提升稳定性的实战心得。应用启动后建议第一时间处理系统弹窗。鸿蒙手机首次启动某些应用时会出现“是否允许访问通讯录”“是否发送通知”等弹窗这些弹窗会遮挡页面元素导致定位失败。我的做法是在测试用例前加一段公共方法循环查找并忽略这些弹窗按钮。另外鸿蒙手机的分辨率碎片化比较大同一应用在不同机型上布局可能发生变化。在写定位表达式时尽量使用resource-id少用坐标点击。使用坐标点击的用例在换机型后基本必挂而且排查成本很高。最后Appium跑鸿蒙手机时如果发现偶发性的无响应或元素超时先检查手机是否进入了休眠或锁屏。测试过程中可以手动在开发者选项里开启“屏幕常亮”或者通过adb命令设置adb shell svc power stayon true我自己的习惯是跑长时间用例前一定会加上这条命令否则屏幕一灭整个session就卡在那里浪费时间。6. 关于鸿蒙NEXT的补充说明前面提过纯血鸿蒙HarmonyOS NEXT不再兼容APKAppium默认方案会失效。我在这里专门补充说明因为你很可能在搜索时遇到这两种信息混在一起。HarmonyOS NEXT下做自动化测试目前更可行的路径是华为官方的DevEco Testing配合unicorn测试框架。它支持HAP应用的启动、点击、滑动、断言等常用操作并且能在DevEco Studio中直接编写和执行。这套体系与传统Appium的API设计有差异但如果你已经理解了自动化测试的底层逻辑切换到它并不难。从2024年下半年开始华为也开放了基于OpenHarmony的测试能力社区里有一些Appium驱动扩展原型项目出现但成熟度还不够。我目前给团队的建议是存量鸿蒙手机继续用Appium这套体系保证回归测试新立项的纯血鸿蒙应用直接上DevEco Testing不要花时间强行适配Appium。写到这里环境配置这条主线已经全部讲完了。我在搭这套环境的过程中最深的感受是鸿蒙手机并没有那么“神奇”它本质上在Android兼容层依然遵循标准协议Appium能跑通也就顺理成章了。真正折腾人的从来不是框架而是环境里那些不起眼的小开关、小版本、小路径。希望这篇能把你的弯路拉直顺利跑通第一个鸿蒙手机上的自动化脚本。