使用 WebdriverIO 编写你的第一个 Appium JavaScript 测试从环境准备到运行验证【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appiumAppium 是构建在 W3C WebDriver 协议之上的跨平台应用自动化框架本指南以 packages/appium/docs/en/quickstart/test-js.md 为核心完整讲解如何在 Node.js 环境中使用官方推荐的 WebdriverIO 客户端库编写并运行第一个 Appium 测试。读完本文你将掌握搭建 WebdriverIO 测试项目、理解 capabilities 关键参数、编写会话生命周期完整的测试脚本以及正确启动 Appium 服务器并运行验证测试的完整流程。前置条件你已经完成了什么本文是 Appium Quickstart 系列的 JavaScript 篇它假定你已经完成了前面两个步骤安装 Appium 服务器通过npm install -g appium全局安装参见 install.md本指南默认你已满足 Node.js^20.19.0 || ^22.12.0 || 24.0.0、npm10的系统要求参见 requirements.md。安装 UiAutomator2 驱动并完成 Android 环境准备包括 Android SDK、ANDROID_HOME/JAVA_HOME环境变量、连接设备或模拟器以及通过appium driver install uiautomator2安装驱动参见 uiauto2-driver.md。由于 Appium 本身基于 Node.js 开发既然你已成功安装并运行过 Appium说明本机的 Node 与 npm 环境必然满足要求这也是 JS 语言在 Appium 生态中“零额外环境成本”的天然优势。第一步初始化 Node.js 测试项目在你的电脑上任意位置创建一个新的项目目录然后在其中初始化一个 Node.js 项目npm init初始化过程中的交互提示包名、版本、描述等输入什么并不重要只要最终能生成一个合法的package.json即可。你可以一路回车接受默认值也可以使用npm init -y直接跳过交互。第二步安装 WebdriverIO 客户端Appium 本身只是服务器测试脚本必须借助客户端库与其通信。目前维护最活跃、且 Appium 官方团队推荐使用的 JS 客户端是 WebdriverIO。在项目目录下执行npm i --save-dev webdriverio安装完成后你的package.json应当包含类似如下的依赖声明。当前仓库自带的示例项目锁定的是 WebdriverIO 9.x 版本线参见 sample-code/quickstarts/js/package.json{ devDependencies: { webdriverio: 9.31.4 } }这里将webdriverio作为 devDependency开发依赖安装因为测试代码只在开发与 CI 阶段运行不会进入生产运行时。WebdriverIO 不仅仅是一个 Appium 客户端它同时也是一个完整的浏览器端 E2E 测试框架在本场景中我们只用到它提供的remote()方法以 WebDriver 协议直接与 Appium 服务器建立会话。第三步编写测试脚本 test.js在项目目录中新建test.js文件内容如下完整代码见 sample-code/quickstarts/js/test.jsconst {remote} require(webdriverio); const capabilities { platformName: Android, appium:automationName: UiAutomator2, appium:deviceName: Android, appium:appPackage: com.android.settings, appium:appActivity: .Settings, }; const wdOpts { hostname: process.env.APPIUM_HOST || localhost, port: parseInt(process.env.APPIUM_PORT, 10) || 4723, logLevel: info, capabilities, }; async function runTest() { const driver await remote(wdOpts); try { const appsItem await driver.$(//*[textApps]); await appsItem.click(); } finally { await driver.pause(1000); await driver.deleteSession(); } } runTest().catch(console.error);这段代码整体做了五件事定义一组capabilities会话能力参数告诉 Appium 服务器你希望自动化什么类型的目标在 Android 系统内置的Settings设置应用上启动一个 Appium 会话通过 XPath 定位Apps列表项并点击它暂停片刻纯粹是为了让运行效果在视觉上可见结束 Appium 会话释放 session。深入解读capabilities 到底在配置什么Capabilities 是启动 Appium 会话的核心参数以键值对形式描述会话所需特性其格式遵循 W3C WebDriver 规范在会话生命周期内不可变更参见 caps.md。上例中的五个参数含义如下参数类型含义platformNamestring目标平台这里是AndroidW3C 标准 capabilityappium:automationNamestring选择使用哪个驱动UiAutomator2对应 uiautomator2 驱动appium:deviceNamestring设备名称示例中填Android即可匹配到已连接的设备appium:appPackagestring要启动应用的包名com.android.settings即系统设置应用appium:appActivitystring要启动的 Activity.Settings是设置应用的主界面注意appium:前缀根据 WebDriver 规范扩展 capability 必须携带供应商命名空间前缀并以冒号结尾Appium 的供应商前缀就是appium:用于与标准 capability如platformName区分。WebdriverIO 不会自动为 Appium 添加此前缀与 Python 客户端会自动添加的行为不同因此必须显式写出。appium:automationName: UiAutomator2正是驱动安装时输出信息中automationName字段的值——这是 Appium 服务器选择具体驱动来接管会话的依据。深入解读连接配置与端口wdOpts对象配置了客户端如何连接 Appium 服务器hostname: process.env.APPIUM_HOST || localhost优先读取环境变量APPIUM_HOST未设置时回退到localhostport: parseInt(process.env.APPIUM_PORT, 10) || 4723优先读取APPIUM_PORT未设置或解析失败时回退到4723这是 Appium 服务器的默认监听端口logLevel: info控制 WebdriverIO 客户端侧的日志详细程度。通过环境变量注入连接参数可以方便地在本地、CI 或远程设备云之间切换目标服务器而无需改动代码。深入解读测试逻辑与资源释放runTest()中的关键调用链值得注意await remote(wdOpts)发起 WebDriver 的new session请求返回 driver 对象await driver.$(//*[textApps])通过XPath 选择器定位文本为 Apps 的 UI 元素。$是 WebdriverIO 查找单个元素的 APIXPath 定位方式在移动端自动化中非常常用await appsItem.click()对定位到的元素执行点击finally块中的driver.pause(1000)与driver.deleteSession()无论测试主体是否抛错都会先暂停 1 秒展示效果再确保会话被关闭。将资源释放放在finally中是良好的健壮性实践避免异常导致会话泄漏。脚本末尾的runTest().catch(console.error)将异步执行过程中的任何异常打印到控制台方便排查。说明本指南不展开讲解 WebdriverIO 客户端库的全部 API每个命令的具体用途建议结合官方 WebdriverIO 文档学习并重点阅读 Appium 的 Capabilities 指南。第四步启动服务器并运行测试启动 Appium 服务器在运行测试脚本之前必须先在一个独立的终端会话中启动 Appium 服务器服务器进程与客户端相互独立必须显式启动否则脚本会因无法连接而报错appium服务器启动成功后控制台日志会列出客户端可用的连接 URL[Appium] You can provide the following URLs in your client code to connect to this server: [Appium] http://127.0.0.1:4723/ (only accessible from the same host) (... any other URLs ...)日志中的4723端口正是 test.js 中默认连接的目标。如果服务器启动时指定了其他端口例如appium --port 4724则需要同步设置APPIUM_PORT环境变量。运行测试脚本服务器就绪后在另一个终端中回到测试项目目录执行node test.js如果一切顺利你会看到 Android 设备或模拟器上的设置应用被打开并自动跳转到 Apps 视图随后应用关闭。与此同时Appium 服务器终端会持续输出本次会话的日志——这是排查测试问题的重要依据一旦测试异常优先检查服务器日志中的详细报错。常见问题与排错思路报错“无法连接到服务器”几乎都是因为 Appium 服务器没有启动或APPIUM_HOST/APPIUM_PORT与实际服务器地址不一致。确认服务器终端已显示连接 URL 后再运行脚本。会话创建失败Session not created检查 capabilities 是否与已安装驱动匹配。appium:automationName必须等于已安装驱动的 automationNameUiAutomator2 驱动对应UiAutomator2同时确认设备在adb devices中可见。找不到 Apps 元素不同 Android 版本/厂商 ROM 的设置界面布局可能不同XPath//*[textApps]并非在所有设备上通用。可以使用 Appium Inspector 之类的工具可视化检查应用元素结构获取准确的选择器参见 next-steps.md。测试只跑一次就需要重新处理如果修改了test.js直接再次执行node test.js即可无需重启 Appium 服务器——服务器与客户端完全解耦。结语与后续探索至此你已经完成了第一个 Appium JavaScript 测试从npm init创建项目、安装 WebdriverIO、编写基于 capabilities 与 XPath 定位的测试脚本到启动服务器并成功运行。这是一个最小的可运行闭环后续可以沿着以下方向深入各指南均位于本仓库 docs 中Ecosystem 总览浏览可用的驱动、客户端、插件与工具管理 Appium 驱动与插件学习appium driver install/appium plugin install等命令细节Capabilities 详解掌握appium:options分组、always-match / first-match 等进阶用法Settings API了解会话运行期如何动态调整驱动行为。值得说明的是本指南中的示例代码package.json与test.js在仓库中的完整出处为 packages/appium/sample-code/quickstarts/js/ 目录你随时可以对照仓库内的原始文件进行校验和复用。【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 WebdriverIO 编写你的第一个 Appium JavaScript 测试：从环境准备到运行验证
使用 WebdriverIO 编写你的第一个 Appium JavaScript 测试从环境准备到运行验证【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appiumAppium 是构建在 W3C WebDriver 协议之上的跨平台应用自动化框架本指南以 packages/appium/docs/en/quickstart/test-js.md 为核心完整讲解如何在 Node.js 环境中使用官方推荐的 WebdriverIO 客户端库编写并运行第一个 Appium 测试。读完本文你将掌握搭建 WebdriverIO 测试项目、理解 capabilities 关键参数、编写会话生命周期完整的测试脚本以及正确启动 Appium 服务器并运行验证测试的完整流程。前置条件你已经完成了什么本文是 Appium Quickstart 系列的 JavaScript 篇它假定你已经完成了前面两个步骤安装 Appium 服务器通过npm install -g appium全局安装参见 install.md本指南默认你已满足 Node.js^20.19.0 || ^22.12.0 || 24.0.0、npm10的系统要求参见 requirements.md。安装 UiAutomator2 驱动并完成 Android 环境准备包括 Android SDK、ANDROID_HOME/JAVA_HOME环境变量、连接设备或模拟器以及通过appium driver install uiautomator2安装驱动参见 uiauto2-driver.md。由于 Appium 本身基于 Node.js 开发既然你已成功安装并运行过 Appium说明本机的 Node 与 npm 环境必然满足要求这也是 JS 语言在 Appium 生态中“零额外环境成本”的天然优势。第一步初始化 Node.js 测试项目在你的电脑上任意位置创建一个新的项目目录然后在其中初始化一个 Node.js 项目npm init初始化过程中的交互提示包名、版本、描述等输入什么并不重要只要最终能生成一个合法的package.json即可。你可以一路回车接受默认值也可以使用npm init -y直接跳过交互。第二步安装 WebdriverIO 客户端Appium 本身只是服务器测试脚本必须借助客户端库与其通信。目前维护最活跃、且 Appium 官方团队推荐使用的 JS 客户端是 WebdriverIO。在项目目录下执行npm i --save-dev webdriverio安装完成后你的package.json应当包含类似如下的依赖声明。当前仓库自带的示例项目锁定的是 WebdriverIO 9.x 版本线参见 sample-code/quickstarts/js/package.json{ devDependencies: { webdriverio: 9.31.4 } }这里将webdriverio作为 devDependency开发依赖安装因为测试代码只在开发与 CI 阶段运行不会进入生产运行时。WebdriverIO 不仅仅是一个 Appium 客户端它同时也是一个完整的浏览器端 E2E 测试框架在本场景中我们只用到它提供的remote()方法以 WebDriver 协议直接与 Appium 服务器建立会话。第三步编写测试脚本 test.js在项目目录中新建test.js文件内容如下完整代码见 sample-code/quickstarts/js/test.jsconst {remote} require(webdriverio); const capabilities { platformName: Android, appium:automationName: UiAutomator2, appium:deviceName: Android, appium:appPackage: com.android.settings, appium:appActivity: .Settings, }; const wdOpts { hostname: process.env.APPIUM_HOST || localhost, port: parseInt(process.env.APPIUM_PORT, 10) || 4723, logLevel: info, capabilities, }; async function runTest() { const driver await remote(wdOpts); try { const appsItem await driver.$(//*[textApps]); await appsItem.click(); } finally { await driver.pause(1000); await driver.deleteSession(); } } runTest().catch(console.error);这段代码整体做了五件事定义一组capabilities会话能力参数告诉 Appium 服务器你希望自动化什么类型的目标在 Android 系统内置的Settings设置应用上启动一个 Appium 会话通过 XPath 定位Apps列表项并点击它暂停片刻纯粹是为了让运行效果在视觉上可见结束 Appium 会话释放 session。深入解读capabilities 到底在配置什么Capabilities 是启动 Appium 会话的核心参数以键值对形式描述会话所需特性其格式遵循 W3C WebDriver 规范在会话生命周期内不可变更参见 caps.md。上例中的五个参数含义如下参数类型含义platformNamestring目标平台这里是AndroidW3C 标准 capabilityappium:automationNamestring选择使用哪个驱动UiAutomator2对应 uiautomator2 驱动appium:deviceNamestring设备名称示例中填Android即可匹配到已连接的设备appium:appPackagestring要启动应用的包名com.android.settings即系统设置应用appium:appActivitystring要启动的 Activity.Settings是设置应用的主界面注意appium:前缀根据 WebDriver 规范扩展 capability 必须携带供应商命名空间前缀并以冒号结尾Appium 的供应商前缀就是appium:用于与标准 capability如platformName区分。WebdriverIO 不会自动为 Appium 添加此前缀与 Python 客户端会自动添加的行为不同因此必须显式写出。appium:automationName: UiAutomator2正是驱动安装时输出信息中automationName字段的值——这是 Appium 服务器选择具体驱动来接管会话的依据。深入解读连接配置与端口wdOpts对象配置了客户端如何连接 Appium 服务器hostname: process.env.APPIUM_HOST || localhost优先读取环境变量APPIUM_HOST未设置时回退到localhostport: parseInt(process.env.APPIUM_PORT, 10) || 4723优先读取APPIUM_PORT未设置或解析失败时回退到4723这是 Appium 服务器的默认监听端口logLevel: info控制 WebdriverIO 客户端侧的日志详细程度。通过环境变量注入连接参数可以方便地在本地、CI 或远程设备云之间切换目标服务器而无需改动代码。深入解读测试逻辑与资源释放runTest()中的关键调用链值得注意await remote(wdOpts)发起 WebDriver 的new session请求返回 driver 对象await driver.$(//*[textApps])通过XPath 选择器定位文本为 Apps 的 UI 元素。$是 WebdriverIO 查找单个元素的 APIXPath 定位方式在移动端自动化中非常常用await appsItem.click()对定位到的元素执行点击finally块中的driver.pause(1000)与driver.deleteSession()无论测试主体是否抛错都会先暂停 1 秒展示效果再确保会话被关闭。将资源释放放在finally中是良好的健壮性实践避免异常导致会话泄漏。脚本末尾的runTest().catch(console.error)将异步执行过程中的任何异常打印到控制台方便排查。说明本指南不展开讲解 WebdriverIO 客户端库的全部 API每个命令的具体用途建议结合官方 WebdriverIO 文档学习并重点阅读 Appium 的 Capabilities 指南。第四步启动服务器并运行测试启动 Appium 服务器在运行测试脚本之前必须先在一个独立的终端会话中启动 Appium 服务器服务器进程与客户端相互独立必须显式启动否则脚本会因无法连接而报错appium服务器启动成功后控制台日志会列出客户端可用的连接 URL[Appium] You can provide the following URLs in your client code to connect to this server: [Appium] http://127.0.0.1:4723/ (only accessible from the same host) (... any other URLs ...)日志中的4723端口正是 test.js 中默认连接的目标。如果服务器启动时指定了其他端口例如appium --port 4724则需要同步设置APPIUM_PORT环境变量。运行测试脚本服务器就绪后在另一个终端中回到测试项目目录执行node test.js如果一切顺利你会看到 Android 设备或模拟器上的设置应用被打开并自动跳转到 Apps 视图随后应用关闭。与此同时Appium 服务器终端会持续输出本次会话的日志——这是排查测试问题的重要依据一旦测试异常优先检查服务器日志中的详细报错。常见问题与排错思路报错“无法连接到服务器”几乎都是因为 Appium 服务器没有启动或APPIUM_HOST/APPIUM_PORT与实际服务器地址不一致。确认服务器终端已显示连接 URL 后再运行脚本。会话创建失败Session not created检查 capabilities 是否与已安装驱动匹配。appium:automationName必须等于已安装驱动的 automationNameUiAutomator2 驱动对应UiAutomator2同时确认设备在adb devices中可见。找不到 Apps 元素不同 Android 版本/厂商 ROM 的设置界面布局可能不同XPath//*[textApps]并非在所有设备上通用。可以使用 Appium Inspector 之类的工具可视化检查应用元素结构获取准确的选择器参见 next-steps.md。测试只跑一次就需要重新处理如果修改了test.js直接再次执行node test.js即可无需重启 Appium 服务器——服务器与客户端完全解耦。结语与后续探索至此你已经完成了第一个 Appium JavaScript 测试从npm init创建项目、安装 WebdriverIO、编写基于 capabilities 与 XPath 定位的测试脚本到启动服务器并成功运行。这是一个最小的可运行闭环后续可以沿着以下方向深入各指南均位于本仓库 docs 中Ecosystem 总览浏览可用的驱动、客户端、插件与工具管理 Appium 驱动与插件学习appium driver install/appium plugin install等命令细节Capabilities 详解掌握appium:options分组、always-match / first-match 等进阶用法Settings API了解会话运行期如何动态调整驱动行为。值得说明的是本指南中的示例代码package.json与test.js在仓库中的完整出处为 packages/appium/sample-code/quickstarts/js/ 目录你随时可以对照仓库内的原始文件进行校验和复用。【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考