使用Appium运行测试用例时出现onPrepare Hook报错如何解决

问题场景 #

基于WebdriverIO框架集成Appium运行自动化测试用例时，执行流程在onPrepare Hook阶段中断，Appium服务启动失败，运行日志与错误堆栈信息如下：

2022-06-20T10:22:26.412Z INFO @wdio/cli:launcher: 运行onPrepare钩子
2022-06-20T10:23:22.099Z ERROR @wdio/cli:utils: 'onPrepare'钩子阶段有服务运行失败
错误：Appium在超时阈值到达前异常退出（退出码: 1）

错误堆栈：

at ChildProcess.<anonymous> (C:\Users\Joyi\Downloads\webdriverio-appium-course-master\webdriverio-appium-course-master\node_modules\@wdio\appium-service\build\launcher.js:110:22)
at Object.onceWrapper (node:events:642:26)
at ChildProcess.emit (node:events:527:28)
at ChildProcess.emit (node:domain:475:12)
at Process.ChildProcess._handle.onexit (node:internal/child_process:291:12)

排查与解决方法 #

按出现概率从高到低依次排查：

• 端口占用：Appium默认使用4723端口启动，若该端口被之前未正常关闭的Appium进程、其他服务占用，会直接导致启动失败返回退出码1。
  Windows环境执行netstat -ano | findstr "4723"查询占用端口的进程ID，再执行taskkill /F /PID 查到的进程ID强制关闭占用进程；Mac/Linux环境执行lsof -i:4723查询占用进程后，执行kill -9 查到的进程ID清理即可。
• 测试环境依赖缺失/配置错误：@wdio/appium-service拉起Appium需要完整的移动端测试环境支撑，安卓端需要正确配置ANDROID_HOME环境变量、将platform-tools、build-tools路径加入系统PATH，iOS端需要正常配置Xcode及命令行工具，任意依赖缺失都会导致Appium启动超时退出。
  先执行npm install -g appium全局安装Appium，再执行appium doctor一键扫描所有依赖项，将所有标红的缺失项补全、环境变量配置生效后再重试。
• wdio配置参数错误：检查wdio.conf.js中services字段下的Appium配置，若错误填写了不存在的Appium可执行文件路径、传入了不兼容的启动参数，会导致服务拉起失败。
  本地全局安装Appium的场景下，可以删除配置中自定义的command路径，让服务自动查找全局Appium可执行文件；移除所有自定义的无效启动参数后重试。
• 启动超时阈值设置过短：@wdio/appium-service默认的服务启动超时时间为60秒，若本地机器性能较差、首次启动需要加载驱动耗时较长，会触发超时阈值被判定为启动失败。
  在wdio.conf.js的Appium服务配置项中增加waitforTimeout: 120000参数，将超时时间调整为2分钟即可。
• Node版本不兼容：若当前使用的Node版本与项目中@wdio/appium-service、Appium的版本不兼容（比如使用过高版本的Node运行多年前的旧版项目依赖），也会出现进程异常退出的问题。
  将Node版本切换至LTS长期支持版本（推荐16.x或18.x版本），重新执行npm install安装项目依赖后重试。

内容的提问来源于stack exchange，提问作者Rahul Chakraborty