企业官网建设流程全解析

使用 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/appium

Appium 是构建在 W3C WebDriver 协议之上的跨平台应用自动化框架，本指南以 packages/appium/docs/en/quickstart/test-js.md 为核心，完整讲解如何在 Node.js 环境中使用官方推荐的 WebdriverIO 客户端库编写并运行第一个 Appium 测试。读完本文，你将掌握：搭建 WebdriverIO 测试项目、理解 capabilities 关键参数、编写会话生命周期完整的测试脚本，以及正确启动 Appium 服务器并运行验证测试的完整流程。

前置条件：你已经完成了什么

本文是 Appium Quickstart 系列的 JavaScript 篇，它假定你已经完成了前面两个步骤：

1. 安装 Appium 服务器：通过npm install -g appium全局安装（参见 install.md），本指南默认你已满足 Node.js^20.19.0 || ^22.12.0 || >=24.0.0、npm>=10的系统要求（参见 requirements.md）。
2. 安装 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.js）：

const {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.$('//*[@text="Apps"]'); await appsItem.click(); } finally { await driver.pause(1000); await driver.deleteSession(); } } runTest().catch(console.error);

这段代码整体做了五件事：

1. 定义一组capabilities（会话能力参数），告诉 Appium 服务器你希望自动化什么类型的目标；
2. 在 Android 系统内置的Settings（设置）应用上启动一个 Appium 会话；
3. 通过 XPath 定位"Apps"列表项并点击它；
4. 暂停片刻，纯粹是为了让运行效果在视觉上可见；
5. 结束 Appium 会话（释放 session）。

深入解读：capabilities 到底在配置什么

Capabilities 是启动 Appium 会话的核心参数，以键值对形式描述会话所需特性，其格式遵循 W3C WebDriver 规范，在会话生命周期内不可变更（参见 caps.md）。上例中的五个参数含义如下：

注意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，未设置时回退到localhost；
• port: 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.$('//*[@text="Apps"]')：通过XPath 选择器定位文本为 "Apps" 的 UI 元素。$是 WebdriverIO 查找单个元素的 API，XPath 定位方式在移动端自动化中非常常用；
• 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 服务器终端会持续输出本次会话的日志——这是排查测试问题的重要依据：一旦测试异常，优先检查服务器日志中的详细报错。

常见问题与排错思路

1. 报错“无法连接到服务器”：几乎都是因为 Appium 服务器没有启动，或APPIUM_HOST/APPIUM_PORT与实际服务器地址不一致。确认服务器终端已显示连接 URL 后再运行脚本。
2. 会话创建失败（Session not created）：检查 capabilities 是否与已安装驱动匹配。appium:automationName必须等于已安装驱动的 automationName（UiAutomator2 驱动对应UiAutomator2）；同时确认设备在adb devices中可见。
3. 找不到 "Apps" 元素：不同 Android 版本/厂商 ROM 的设置界面布局可能不同，XPath//*[@text="Apps"]并非在所有设备上通用。可以使用 Appium Inspector 之类的工具可视化检查应用元素结构，获取准确的选择器（参见 next-steps.md）。
4. 测试只跑一次就需要重新处理：如果修改了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