跳至内容

迁移到 Appium 2

本文档是针对那些使用 Appium 1 并希望迁移到 Appium 2 的用户的指南。它包含一个重大变更列表以及如何迁移您的环境或测试套件以确保与 Appium 2 的兼容性。

Appium 2 概述

Appium 2 是 Appium 5 年多来最重大的新版本。Appium 2 中的更改并非主要与特定平台的自动化行为更改相关。相反，Appium 2 将 Appium 重新设想为一个平台，其中“驱动程序”（引入对给定平台自动化的支持的代码项目）和“插件”（允许覆盖、更改、扩展或添加 Appium 行为的代码项目）可以轻松创建和共享。

同时，Appium 项目正在抓住机会删除许多旧的和已弃用的功能。

这些更改共同引入了对 Appium 的安装方式、驱动程序和各种功能的管理方式以及协议支持的一些重大变更。这些将在下面详细说明。

重大变更

‼ 默认服务器基本路径

在 Appium 1 中，服务器默认情况下会通过 http://localhost:4723/wd/hub 接受命令。/wd/hub 基本路径是 Selenium 1 迁移到 Selenium 2 时代的遗留约定，现在不再相关。因此，服务器的默认基本路径现在是 /。如果您想保留旧的行为，您可以通过以下命令行参数设置基本路径

appium --base-path=/wd/hub

您也可以将服务器参数设置为 配置文件 属性。

‼ 在设置期间安装驱动程序

当您安装 Appium 1 时，所有可用的驱动程序都会与主 Appium 服务器同时安装。现在不再是这样。只需安装 Appium 2（例如，通过 npm i -g appium），将仅安装 Appium 服务器，但不会安装任何驱动程序。要安装驱动程序，您必须使用新的 Appium 扩展 CLI。例如，要安装最新版本的 XCUITest 和 UiAutomator2 驱动程序，在安装 Appium 后，您需要运行以下命令

appium driver install uiautomator2     # installs the latest driver version
appium driver install [email protected]  # installs a specific driver version

此时，您的驱动程序已安装并可以使用。您可以使用 Appium 2 命令行执行更多操作，因此请务必查看 其文档。如果您在 CI 环境中运行，或者想要在一步中安装 Appium 和一些驱动程序，您可以使用安装过程中的某些特殊标志来实现，例如

npm i -g appium --drivers=xcuitest,uiautomator2

这将在一步骤中为您安装 Appium 和两个驱动程序。如果您遇到安装或启动错误，请卸载任何现有的 Appium 1 npm 包（使用 npm uninstall -g appium）。

‼ 驱动程序安装路径

当您安装 Appium 1 时，所有可用的驱动程序都会与主 Appium 服务器同时安装，位于 /path/to/appium/node_modules。例如，appium-webdriveragent 位于 /path/to/appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent。

Appium 2 将此类依赖项安装在由 APPIUM_HOME 环境变量定义的路径中。默认路径是 ~/.appium。因此，appium-webdriveragent 现在将位于 $APPIUM_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent。

‼ Chromedriver 安装标志

在 Appium 1 中，可以使用以下命令行标志自定义 Chromedriver 的安装方式（例如，作为 UiAutomator2 驱动程序的一部分）。

  • --chromedriver-skip-install
  • --chromedriver-version
  • --chromedriver-cdnurl

由于 Appium 2 现在为您安装驱动程序，并且由于这些标志是作为 npm 配置标志实现的，因此它们将不再起作用。相反，在驱动程序安装期间使用以下环境变量

  • APPIUM_SKIP_CHROMEDRIVER_INSTALL
  • CHROMEDRIVER_VERSION
  • CHROMEDRIVER_CDNURL

例如

APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2

‼ 特定于驱动程序的命令行选项

在 Appium 1 中，特定于特定驱动程序的命令行选项都托管在主 Appium 服务器上。因此，例如，--chromedriver-executable 是您可以与 Appium 一起使用的 CLI 参数，用于设置特定 Chromedriver 版本的位置，以用于例如 UiAutomator2 驱动程序。

在 Appium 2 中，所有特定于驱动程序和平台的 CLI 参数都已移至驱动程序本身。要访问相应的功能，您需要参考驱动程序/插件文档。在某些情况下，扩展将继续公开 CLI 参数。例如，XCUITest 驱动程序过去会公开参数 --webdriveragent-port。现在，要访问此参数，它应该以 driver-xcuitest 为前缀，以将其与其他驱动程序可能公开的参数区分开来。因此，要使用此参数，您需要使用类似以下内容启动 Appium

appium --driver-xcuitest-webdriveragent-port=5000

一些驱动程序已经完全放弃了 CLI 参数，转而使用默认功能。例如，对于上面提到的 --chromedriver-executable 参数，您现在需要利用 UiAutomator2 驱动程序支持的 appium:chromedriverExecutable 功能。要从命令行设置此功能，请执行以下操作

appium --default-capabilities '{"appium:chromedriverExecutable": "/path/to/chromedriver"}'

‼ 特定于驱动程序的自动化命令

仅与特定驱动程序相关的某些命令的定义已移至这些驱动程序的实现中。例如，pressKeyCode 特定于 UiAutomator2 驱动程序，现在仅由该驱动程序理解。实际上，这里唯一的重大变更是在未安装适当驱动程序的情况下遇到的错误类型。以前，如果您使用未实现该命令的驱动程序，您将收到 501 Not Yet Implemented 错误。现在，您将收到 404 Not Found 错误，因为如果不知道该命令的驱动程序未处于活动状态，则主 Appium 服务器将不会定义与该命令相对应的路由。

‼ 驱动程序更新

在过去，要获取 iOS 或 Android 驱动程序的更新，您只需等待这些更新被整合到 Appium 的新版本中，然后更新您的 Appium 版本。在 Appium 2 中，Appium 服务器和 Appium 驱动程序是独立版本化和发布的。这意味着驱动程序可以拥有自己的发布节奏，您可以立即获得最新的驱动程序版本，而不是等待新的 Appium 服务器版本。检查驱动程序更新的方法是使用 CLI

appium driver list --updates

如果存在任何更新，您就可以对任何给定的驱动程序运行 update 命令

appium driver update xcuitest

（有关 update 命令的完整描述，请查看 扩展 CLI 文档）

要更新 Appium 服务器本身，您需要执行与过去相同的操作：npm install -g appium。现在，安装 Appium 服务器的新版本将保留您的驱动程序，因此整个过程将快得多。

如果您想更新到特定版本的驱动程序，而不是最新版本，请卸载驱动程序并使用install子命令而不是update安装所需的版本。

appium driver uninstall xcuitest
appium driver install [email protected]

‼ 协议变更

Appium 的 API 基于 W3C WebDriver 协议，并且多年来一直支持该协议。在 W3C WebDriver 协议被设计为 Web 标准之前，Selenium 和 Appium 都使用过其他几种协议。这些协议是“JSONWP”（JSON 线程协议）和“MJSONWP”（移动 JSON 线程协议）。W3C 协议在几个小方面与 (M)JSONWP 协议不同。

直到 Appium 2，Appium 都支持这两种协议，以便旧的 Selenium/Appium 客户端仍然可以与较新的 Appium 服务器通信。Appium 2 取消了对旧协议的支持，现在仅与 W3C WebDriver 协议兼容。

‼ 功能必须使用供应商前缀

旧协议和新协议之间的一个重大区别在于功能的格式。以前称为“所需功能”，现在简称为“功能”，现在要求对任何非标准功能使用所谓的“供应商前缀”。标准功能列表在 WebDriver 协议规范 中给出，包括一些常用的功能，例如browserName 和 platformName。

这些标准功能继续按原样使用。所有其他功能必须在其名称中包含“供应商前缀”。供应商前缀是一个字符串，后跟一个冒号，例如appium:。Appium 的大多数功能超出了标准的 W3C 功能，因此必须包含供应商前缀（我们建议您使用appium:，除非文档另有说明）。例如

  • appium:app
  • appium:noReset
  • appium:deviceName

此要求对于您的测试套件在针对 Appium 2 时是否构成重大更改可能会有所不同。如果您使用的是更新的 Appium 客户端（至少是由 Appium 团队维护的客户端），该客户端将在所有必要的功能上自动为您添加appium: 前缀。新版本的 Appium Inspector 也将执行此操作。基于云的 Appium 提供商也可能执行此操作。因此，只要知道，如果您收到有关您的功能缺少供应商前缀的任何消息，这就是解决该问题的办法。

为了让每个人的生活更轻松，我们还引入了将所有与 Appium 相关的功能分组到一个对象功能appium:options 中的选项。您可以将您通常会为其添加appium: 前缀的任何内容捆绑到此功能中。以下是如何使用appium:options 在 Safari 浏览器上启动 iOS 会话的示例（以原始 JSON 格式）

{
  "platformName": "iOS",
  "browserName": "Safari",
  "appium:options": {
    "platformVersion": "14.4",
    "deviceName": "iPhone 11",
    "automationName": "XCUITest"
  }
}

（当然，每个客户端都有不同的方法来创建结构化功能，例如appium:options 或您可能见过的其他功能，例如goog:chromeOptions）。

注意

包含在appium:options 对象中的功能将覆盖在该对象之外使用的相同名称的功能。（云提供商支持的appium:options 语法可能会有所不同。）

有关功能的更多信息，请查看 功能指南。

‼ 已移除的命令

除了已移至驱动程序实现的命令外，旧 JSON 线程协议的一部分但不是 W3C 协议的一部分的命令也不再可用

  • 待办事项（这些命令正在被识别和移除，并在完成时在此处更新）

如果您使用的是现代 Appium 或 Selenium 客户端，您应该不再能够访问这些命令，因此任何重大更改都应该首先出现在客户端侧。

‼ 图像分析功能已移至插件

Appium 2 的设计目标之一是将非核心功能迁移到称为 插件 的特殊扩展中。这使人们可以选择使用需要额外时间下载或额外系统设置的功能。Appium 的各种与图像相关的功能（图像比较、通过图像查找元素等）已移至一个名为 images 的官方支持插件中。

如果您使用这些与图像相关的功能，要继续访问它们，您需要执行以下两件事

  1. 安装插件：appium plugin install images
  2. 确保您启动 Appium 服务器，使其能够通过在命令行上指定插件列表中包含该插件来运行该插件，例如appium --use-plugins=images

与图像相关的命令也将从客户端侧移除，这意味着您需要按照插件自述文件中的说明安装客户端插件才能访问这些功能。

‼ 执行驱动程序脚本命令已移至插件

如果您使用高级执行驱动程序脚本功能（允许您发送 WebdriverIO 脚本以使其完全在服务器上执行，而不是从客户端逐个命令执行），此功能已移至插件。以下是如何继续使用它的方法

  1. 安装插件：appium plugin install execute-driver
  2. 确保您启动 Appium 服务器，使其能够通过在命令行上指定插件列表中包含该插件来运行该插件，例如appium --use-plugins=execute-driver

‼ --nodeconfig、--default-capabilities、--allow-insecure 和 --deny-insecure 不再支持外部文件

这些选项可以在命令行上作为字符串提供（对于--nodeconfig 为 JSON 字符串，对于--allow-insecure 和 --deny-insecure 为用逗号分隔的字符串列表）。在命令行上提供的参数可能需要加引号或转义。

提供这些选项的推荐方法是通过 配置文件。

总之，如果您使用的是 JSON Appium 配置文件，您可以简单地将“nodeconfig” JSON 文件的内容剪切粘贴到server.nodeconfig 属性的值中。您之前为--allow-insecure 和 --deny-insecure 提供的任何类似 CSV 的文件都将成为 Appium 配置文件（分别）中server.allow-insecure 和 server.deny-insecure 属性的值；两者都是字符串数组。

‼ 已移除旧驱动程序

已移除旧的 iOS 和 Android（UiAutomator 1）驱动程序以及相关工具（例如authorize-ios）。它们已经很多年没有相关性了。

‼ 服务器不再能够使用--port 0 启动

在 Appium 1 中，可以在服务器启动期间指定--port 0。这将启动 Appium 在随机的空闲端口上。在 Appium 2 中，端口值必须为1 或更高。随机端口分配从来不是 Appium 1 的有意功能，而是 Node 的 HTTP 服务器的工作方式以及 Appium 1 中没有端口输入验证的结果。如果您想找到一个随机的空闲端口来启动 Appium，您现在必须在启动 Appium 之前自行处理此问题。在明确且已知的端口上启动 Appium 是今后正确的做法。

⚠ 内部包已重命名

一些 Appium 内部 NPM 包已重命名（例如，appium-base-driver 现在是@appium/base-driver）。这对 Appium 用户来说不是重大更改，只是对直接包含 Appium 代码的人来说是重大更改。

⚠ wd JavaScript 客户端库不再受支持

多年来，Appium 的一些作者维护了 WD 客户端库。该库已被弃用，并且尚未更新以用于 W3C WebDriver 协议。因此，如果您使用的是此库，您需要迁移到更现代的库。我们推荐 WebdriverIO。

⚠ Appium Desktop 已被 Appium Inspector 取代

Appium Desktop 的检查器功能已移至其自己的应用程序：Appium Inspector。它与独立的 Appium 2 服务器完全兼容，但也适用于 Appium 1 服务器的更高版本。Appium Desktop 本身已被弃用，与 Appium 2 不兼容。

除了应用程序外，Appium Inspector 还具有浏览器版本，可通过 inspector.appiumpro.com 访问。请注意，要将浏览器版本与本地 Appium 服务器一起使用，您需要先使用--allow-cors 标志启动服务器。

主要新功能

除了上面提到的重大更改外，本节列出了您可能希望在 Appium 2 中利用的一些主要新功能。

插件

🎉 服务器插件

Appium 扩展作者现在可以开发自己的服务器插件，这些插件可以拦截和修改任何 Appium 命令，甚至可以调整底层 Appium HTTP 服务器本身的工作方式。要详细了解插件，请阅读新的 Appium 简介。有兴趣构建插件吗？查看 构建插件 指南。

🎉 从任何地方安装驱动程序和插件

您不再局限于随 Appium 提供的驱动程序，甚至不再局限于 Appium 团队知道的驱动程序！Appium 扩展作者现在可以开发自定义驱动程序，这些驱动程序可以通过 Appium 的 扩展 CLI 从npm、git、GitHub 甚至本地文件系统下载或安装。有兴趣构建驱动程序吗？查看 构建驱动程序 指南。

🎉 配置文件

Appium 现在除了命令行参数之外还支持配置文件。简而言之，Appium 1 要求在 CLI 上提供的几乎所有参数现在都可以通过配置文件来表达。配置文件可以是 JSON、JS 或 YAML 格式。有关完整说明，请参阅 配置指南。

针对云提供商的特别说明

本文档的其余部分适用于 Appium，但 Appium 2 中的一些架构更改将构成对 Appium 相关服务提供商的重大更改，无论是基于云的 Appium 主机还是内部服务。归根结底，Appium 服务器的维护者负责安装和提供最终用户可能希望使用的各种 Appium 驱动程序和插件。

我们鼓励云提供商仔细阅读并理解我们的云提供商能力建议，以便以行业兼容的方式支持用户需求！