Node.js 18运行移动应用测试时无法连接http://localhost:4723/wd/hub

环境说明 #

• 测试框架：WebdriverIO + Cucumber.js
• 正常环境：Node.js 16.20.2（npm v8.19.4）+ Appium@2.8.0 + XCUITest@5.8.1，iOS应用测试可正常执行
• 异常环境：Node.js 18.20.3（npm v10.7.0）+ 相同版本的Appium和XCUITest，iOS Safari浏览器测试正常，但iOS应用测试出现连接失败错误

错误日志 #

Unable to connect to "http://localhost:4723/wd/hub", make sure browser driver is running on that address.
If you use services like chromedriver see initialiseServices logs above or in wdio.log file as the service might had problems to start the driver.
    at Runtime.runTestRunHooks (/private/tmp/scratchEmNi2G.scratch/test-packagesbz9OA/node_modules/<my-package>/node_modules/@cucumber/cucumber/lib/runtime/run_test_run_hooks.js:23:23)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Runtime.start (/private/tmp/scratchEmNi2G.scratch/test-packagesbz9OA/node_modules/<my-package>/node_modules/@cucumber/cucumber/lib/runtime/index.js:53:9)
    at async runCucumber (/private/tmp/scratchEmNi2G.scratch/test-packagesbz9OA/node_modules/<my-package>/node_modules/@cucumber/cucumber/lib/api/run_cucumber.js:106:21) {
  jse_shortmsg: 'a BeforeAll hook errored, process exiting: node_modules/<my-package>/dist/myfile.js:72',
  jse_cause: Error: Failed to create session.
  Unable to connect to "http://localhost:4723/wd/hub", make sure browser driver is running on that address.
  If you use services like chromedriver see initialiseServices logs above or in wdio.log file as the service might had problems to start the driver.
      at startWebDriverSession (file:///private/tmp/scratchEmNi2G.scratch/test-packagesbz9OA/node_modules/<my-package>/node_modules/webdriver/build/utils.js:68:15)
      at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
      at async WebDriver.newSession (file:///private/tmp/scratchEmNi2G.scratch/test-packagesbz9OA/node_modules/<my-package>/node_modules/webdriver/build/index.js:26:45)
      at async remote (file:///private/tmp/scratchEmNi2G.scratch/test-packagesbz9OA/node_modules/<my-package>/node_modules/webdriverio/build/index.js:48:22),
  jse_info: {},
  cause: [Function: ve_cause]
}

排查与解决方法 #

1. 确认Appium服务状态 #

• 手动启动Appium服务，执行appium命令，查看控制台是否有启动报错（比如端口被占用、依赖缺失）
• 用curl http://localhost:4723/wd/hub/status测试端口连通性，正常会返回包含"ready": true的JSON响应

2. 检查WebdriverIO配置 #

• 对比Node.js 16和18环境下的wdio配置文件，重点确认：
  • Appium服务的hostname、port配置是否正确
  • iOS应用测试的capabilities参数（如app路径、bundleId）是否存在路径解析问题（Node.js 18对路径处理可能有差异）
• 重新安装依赖：删除node_modules和package-lock.json，执行npm install，注意查看安装过程中的警告或错误

3. 适配Node.js 18的兼容性 #

• 更新WebdriverIO相关依赖到最新兼容版本：

  npm update webdriverio @wdio/cli @wdio/cucumber-framework @wdio/appium-service
  

• 检查XCUITest驱动兼容性：执行appium driver run xcuitest --check，确认驱动与Node.js 18的适配情况，必要时更新驱动

4. 权限与环境变量检查 #

• 确认测试应用的路径有读取权限，Node.js 18对文件系统权限要求更严格
• 检查环境变量PATH是否包含Appium、Xcode命令行工具的路径，避免因路径缺失导致驱动无法启动

内容的提问来源于stack exchange，提问作者Aduait Pokhriyal