Appium 1 迁移到 Appium 2 完整指南破坏性变更、驱动/插件生态与配置迁移实战【免费下载链接】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 1 并计划迁移到 Appium 2 的测试开发人员与测试基础设施维护者。Appium 2 是该框架近五年来最重要的一次架构级发布其核心思路不再局限于某个平台的具体自动化行为而是将 Appium 重塑为以 W3C WebDriver 协议为核心、由独立驱动Driver与插件Plugin扩展构成的自动化生态。读完本文你将系统掌握 Appium 1 到 Appium 2 的全部破坏性变更Drivers 独立安装与更新、APPIUM_HOME路径变化、默认 base path 变更、appium:能力前缀、旧协议废弃、CLI 选项变化等以及配置文件、第三方扩展、云服务商适配等新特性的实战用法可直接据此改造现有测试套件与 CI 环境。Appium 2从单体服务器到扩展生态Appium 2 的定位与 Appium 1 有本质区别。它并不聚焦于改变某个特定平台的自动化行为而是重新构想了 Appium 的组织形态见 迁移指南原文核心 Appium 模块只保留与平台无关的功能会话管理、HTTP 服务、协议解析、日志等通用能力。特定平台的自动化功能被拆分到独立的 driver 模块例如 iOS 的 XCUITest、Android 的 UiAutomator2各自独立发布、独立升级。用于修改/扩展 Appium 行为的功能被拆分到独立的 plugin 模块例如图片查找、Execute Driver Script 等高级特性。与此同时Appium 项目借此次大版本重构的机会清理了大量陈旧或已废弃的功能。特别提醒由于这是一次重大架构变更官方不推荐直接对 Appium 1 安装执行原地升级正确的做法是先卸载 Appium 1再全新安装 Appium 2。破坏性变更清单与迁移动作以下按原文档顺序逐项列出破坏性变更并为每一项给出动作清单Actions Needed与源码级佐证。Drivers 改为独立安装安装 Appium 1 时所有官方驱动会随主服务器一起装好而 Appium 2 采用模块化结构默认只安装核心服务器不附带任何驱动。安装驱动的途径有三条安装 Appium 时通过--drivers标志顺带安装npm i -g appium --driversxcuitest,uiautomator2使用 Appium Extension CLIappium driver install uiautomator2使用 Appium2.6新增的 Appium Setup CLI 命令按预设一键安装整组扩展appium setup mobile动作清单安装 Appium 2 时务必使用上述任一方式安装你需要的驱动否则服务器将不认识任何设备。关于第 3 种方式仓库中的 setup.md 给出了完整预设说明appium setup mobile会安装移动测试所需的uiautomator2、xcuitest仅 macOS、espresso驱动以及images、inspector插件mobile可省略直接运行appium setup此外还有browsersafari/gecko/chromium 驱动 images/inspector 插件、desktopmac2/windows 驱动 images/inspector 插件与reset清空 Appium 主目录下全部扩展及 manifest可用于修复升级失败导致的启动配置问题等子命令。Driver 安装路径变更APPIUM_HOMEAppium 1 中驱动作为主服务器的依赖装在/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_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent。这一设计在源码中得到印证extension-config.ts 中扩展的安装根目录被解析为path.join(this.appiumHome, node_modules, ...)即$APPIUM_HOME/node_modules/pkgName并维护一份位于$APPIUM_HOME/node_modules/.cache/appium/extensions.yaml的扩展清单manifest。更多细节可参考 Managing Drivers and Plugins 指南该指南还展示了如何利用APPIUM_HOME在同一台机器上并行管理不同版本的同一驱动APPIUM_HOME/path/to/home1 appium driver install xcuitest4.11.1 APPIUM_HOME/path/to/home2 appium driver install xcuitest4.11.2 APPIUM_HOME/path/to/home1 appium # 使用 xcuitest 驱动 4.11.1 APPIUM_HOME/path/to/home2 appium # 使用 xcuitest 驱动 4.11.2动作清单如果你的代码中硬编码了 Appium 驱动文件路径请改用APPIUM_HOME环境变量动态拼接。Drivers 可独立更新Appium 1 中驱动更新只能等新版本 Appium 发布后整体升级Appium 2 中服务器与驱动是相互独立的 npm 包可各自独立发版无需等待服务器新版本即可安装最新驱动。检查更新使用 Appium Extension CLIappium driver list --updates有可用更新时对指定驱动执行更新appium driver update xcuitest升级 Appium 服务器本身与以往相同npm update -g appium但由于驱动不再捆绑在服务器包中这一过程明显更快。需要注意Extension CLI 的update子命令默认只升级 minor 与 patch 版本以避免破坏性变更如需升级大版本需加--unsafe如appium driver update uiautomator2 --unsafeappium plugin update installed则可一次更新全部已安装插件。动作清单请统一使用 Appium Extension CLI 来管理你的驱动。废弃包不再受支持Appium 1 生态中存在一批已被替代的驱动、客户端等包Appium 2 不再支持它们官方给出的替换对照如下Appium 1 包Appium 2 中的替代iOS DriverXCUITest DriverUiAutomator DriverUiAutomator2wdClientWebdriverIO ClientAppium DesktopAppium Inspector动作清单如果你正在使用上表所列的任一包请迁移到推荐替代品。默认服务器 Base Path 变更Appium 1 的默认服务器地址是http://localhost:4723/wd/hub其中/wd/hub是源自 Selenium 1 的历史遗留约定。Appium 2 将默认 base path 改为/因此默认地址变为http://localhost:4723/。如需沿用旧地址可通过--base-path/wd/hub命令行参数 启动服务器对应--base-path,-pa参数默认值为。该参数在源码中贯穿服务器启动链路它会被归一化后用于路由前缀见 main-helpers.ts 中的normalizeBasePath并参与 BiDi WebSocket 地址拼装与 Selenium Grid 节点注册 URL 的构造见 appium.ts 与 grid-v3-register.ts 中http://${addr}:${port}${basePath}的拼接逻辑。动作清单在测试脚本中把目标服务器 URL 的 base path 从/wd/hub改为/或者用--base-path/wd/hub保留旧路径。不再支持端口 0Appium 1 支持--port 0其效果是让服务器启动在一个随机空闲端口上Appium 2 取消了这一特性端口值必须是1或更大。若仍需随机端口需自行在启动前探测并指定一个可用端口。服务器相关参数可参见 server.md默认端口4723。动作清单若你正在以--port 0启动 Appium请改为1或更大的具体端口号。Driver 专属 CLI 选项发生变化Appium 1 中特定驱动专属的命令行选项全部挂在主服务器上例如用--chromedriver-executable为 UiAutomator2 驱动指定 Chromedriver 位置。Appium 2 中所有驱动专属 CLI 选项都移到了驱动自身但传递方式因驱动而异部分选项仍可作为 CLI 标志传递只是改名为带驱动前缀的形式appium --webdriveragent-port5000 # Appium 1 appium --driver-xcuitest-webdriveragent-port5000 # Appium 2部分选项改为通过环境变量传递appium --chromedriver-version100 # Appium 1 CHROMEDRIVER_VERSION100 appium # Appium 2部分选项改为通过 capabilities 传递appium --chromedriver-executable/path/to/chromedriver # Appium 1 {appium:chromedriverExecutable: /path/to/chromedriver} # Appium 2动作清单如果你使用了驱动专属 CLI 选项请查阅对应驱动文档确认在 Appium 2 中应如何传递CLI 标志 / 环境变量 / capability 三选一。部分 CLI 选项不再接受文件路径Appium 1 中以下四个服务器选项支持传入文件路径Appium 会自动读取文件内容作为选项值--nodeconfig--default-capabilities--allow-insecure--deny-insecureAppium 2 不再解析这些选项的文件路径内容改为两种指定方式直接在命令行以字符串形式传递--nodeconfig/--default-capabilitiesJSON 字符串--allow-insecure/--deny-insecure逗号分隔列表放在 Appium 配置文件 中此时以原生类型书写例如--use-plugins在配置文件里就是数组[my-plugin, some-other-plugin]。动作清单如果你曾以文件路径形式使用上述选项请改为直接传值或通过配置文件提供。旧协议被移除Appium 的 API 基于 W3C WebDriver 协议并已支持多年。在它成为 Web 标准之前业界先后使用 JSON Wire ProtocolJSONWP与 Mobile JSON Wire ProtocolMJSONWP。Appium 1 同时支持这三种协议以兼容旧版 Selenium/Appium 客户端Appium 2 移除了 JSONWP/MJSONWP 支持仅兼容 W3C WebDriver 协议。动作清单确保你使用的是兼容 W3C WebDriver 协议的 Selenium/Appium 客户端。Capabilities 必须使用 Vendor PrefixAppium 1 中创建会话需指定若干 desired capabilitiesAppium 2 延续了这一行为desired capabilities 现统称 capabilities但按照 W3C WebDriver 规范所有非标准 capability 都必须带 vendor prefix。标准 capability 由 W3C 规范定义常见的有browserName、platformName等Capabilities Guide 中列出的标准项还包括browserVersion。其余 capability 必须以供应商名加冒号开头如moz:、goog:。由于 Appium 绝大多数 capability 超出标准范围它们都必须带appium:前缀deviceName # Appium 1 appium:deviceName # Appium 2这一要求是否构成破坏性变更取决于你的测试套件较新版本的官方 Appium 客户端与 Appium Inspector 会自动为非标准 capability 补上appium:前缀部分云 Appium 服务商也会自动处理。为避免逐个加前缀显得冗余可把 Appium 专属 capability 统一收进单个对象型 capabilityappium:options默认写法{ platformName: iOS, browserName: Safari, appium:platformVersion: 14.4, appium:deviceName: iPhone 11, appium:automationName: XCUITest }使用appium:options的写法{ platformName: iOS, browserName: Safari, appium:options: { platformVersion: 14.4, deviceName: iPhone 11, automationName: XCUITest } }警告appium:options对象内的 capability 会覆盖同名的外部 capability即内层优先且各云服务商对appium:options语法的支持程度可能不同。能力capabilities是启动 Appium 会话的核心参数在会话生命周期内不可变更驱动若需在会话中动态调整行为应使用 Settings API。更多能力说明见 Capabilities Guide基础驱动支持的全部能力见 会话能力参考。动作清单为测试中所有 Appium 专属 capability 加上appium:前缀或统一放入appium:options对象。高级功能迁移到插件Appium 2 的设计目标之一是把非核心功能抽取为名为 plugins 的特殊扩展。Appium 1 中有两项功能已迁出并不再随 Appium 2 内置功能插件名称仓库内对应包图像相关功能图像比较、按图搜索等imagespackages/images-pluginExecute Driver Script 功能execute-driverpackages/execute-driver-plugin动作清单如果你在 Appium 1 中使用过图像功能或 Execute Driver Script请先安装对应插件appium plugin install images appium plugin install execute-driver然后启动服务器时必须激活插件appium --use-pluginsimages,execute-driver--use-plugins默认不激活任何插件设为[all]可激活全部已安装插件对应参数详见 server.md。端点参数变更Appium 1 的部分服务器端点曾接受旧参数或无用参数Appium 2 移除了这些参数。变更清单如下✗ 为不再接受的参数✓ 为 Appium 2 继续接受的参数POST /session/:sessionId/appium/device/gsm_signal✗signalStrengh拼写错误的历史参数✓signalStrengthPOST /session/:sessionId/appium/element/:elementId/value✗value✓textPOST /session/:sessionId/appium/element/:elementId/replace_value✗value✓text动作清单查阅你的 Appium 客户端文档中调用这些端点的方法并修改代码只使用被接受的参数。内部包重命名Appium 1 中内部依赖包各自位于独立仓库Appium 2 改为 monorepo 结构并重命名了其中大量包例如appium-base-driver # Appium 1 appium/base-driver # Appium 2本仓库即采用该 monorepo 结构packages/目录下可以看到 appium/base-driver、appium/base-plugin、appium/support、appium/types、appium/schema 等以appium/为作用域的包。动作清单如果你没有直接在代码中 import Appium 的包无需任何操作如果有请更新包名。Appium 2 的主要新特性除破坏性变更外Appium 2 还带来以下值得利用的新能力第三方驱动与插件Appium 2 不再局限于官方或 Appium 团队已知的驱动/插件——开发者可以自行编写驱动或插件并通过 Extension CLI 从npm、git、GitHub 甚至本地文件系统安装。install子命令的--source选项控制安装来源取值git、github、local、npm并相应改变install-spec的格式sourceinstall-spec格式无官方扩展短名可带 npm install 支持的版本/tag 修饰git扩展的 Git URLgithub扩展的 GitHub 仓库 URLlocal包含package.json的本地路径npmnpm 包名可带版本/tag 修饰典型示例appium driver install xcuitest9.0.0 appium driver install appium/fake-driverbeta --sourcenpm appium plugin install /path/to/my/plugin --sourcelocal appium driver install github-url --sourcegithub --packageappium-xcuitest-driver appium driver install git://git-url.git#specific-branch --sourcegit --packageappium-xcuitest-driver本仓库就是扩展开发的一手参考packages/fake-driver与packages/fake-plugin提供了最小可运行的驱动/插件实现与对应 schema 校验fake-driver-schema.ts、fake-plugin-schema.tspackages/driver-test-support与packages/plugin-test-support则提供了编写驱动/插件测试的支撑设施。Extension CLI 还支持list含--installed、--updates、--verbose、--json、run运行扩展自带脚本如appium driver run uiautomator2 reset、doctor运行扩展的医生检查如appium driver doctor uiautomator2与uninstall等子命令详见 extensions.md。配置文件Appium 2 在命令行参数之外新增了配置文件支持几乎所有 Appium 1 中必须通过 CLI 指定的选项现在都能写进配置文件。格式支持 JSON、YAML、JS/CJS注意ESM 格式暂不支持。配置文件以server为根属性参数为其子属性CLI 中需要逗号分隔字符串、JSON 字符串或文件路径的参数在配置文件中使用原生类型。{ server: { use-plugins: [my-plugin, some-other-plugin] } }驱动与插件专属配置分别位于server.driver与server.plugin属性下键名与扩展包名对应且全部属性区分大小写并使用 kebab-case如callback-port合法callbackPort不合法{ server: { driver: { xcuitest: { webkit-debug-proxy-port: 5400 } } } }上述配置等价于 CLI 参数--driver-xcuitest-webkit-debug-proxy-port。Appium 会从当前工作目录向上逐级搜索配置文件支持.appiumrc.json推荐、.appiumrc.yaml/.yml、.appiumrc.js/.cjs、appium.config.js/.cjs、.appiumrc按 JSON 解析以及 Node.js 项目中package.json里的appium属性也可用appium --config /path/to/config/file指定自定义位置。仓库内提供了三种格式的完整示例appium.config.sample.json、appium.config.sample.yaml、appium.config.sample.js以及配置的 JSON Schema 定义appium-config.schema.json。完整说明见 Config File Guide。注意CLI 参数的优先级高于配置文件二者同时设置时以 CLI 为准。给云服务商的特别提示上述内容大多面向 Appium 终端用户或开发者但 Appium 2 的部分架构变化对各类 Appium 服务提供方云厂商而言同样是破坏性变更——归根结底Appium 服务器的维护者负责安装并向终端用户暴露各类驱动与插件。云厂商需要仔细阅读并理解社区对云服务商 capability 的建议相关讨论集中在 Capabilities Guide 的云服务商章节以兼容行业通行的方式支撑用户需求例如采用$cloud:appiumOptions风格的 capability其中$cloud应替换为各家自己的 vendor 前缀用version、automationVersion、automation、plugins等键描述所需的服务器版本、驱动版本、自定义驱动与插件清单。迁移检查清单完成 Appium 1 → 2 迁移前建议逐项核对卸载 Appium 1全新安装 Appium 2并同时安装所需驱动--drivers/appium driver install/appium setup mobile三选一更新任何硬编码的驱动文件路径改用APPIUM_HOME环境变量改用 Extension CLI 管理驱动更新appium driver list --updates、appium driver update替换已废弃的包iOS Driver→XCUITest、UiAutomator Driver→UiAutomator2、wd→WebdriverIO、Appium Desktop→Appium Inspector测试脚本中服务器 URL 的 base path 改为/或启动时加--base-path/wd/hub去掉--port 0显式使用1及以上端口按各驱动文档迁移驱动专属 CLI 选项CLI 标志 / 环境变量 / capability 三种形态不再向--nodeconfig等四个选项传文件路径改为直接传值或写入配置文件确认客户端兼容 W3C WebDriver 协议为所有非标准 capability 添加appium:前缀或用appium:options归组若使用图像功能或 Execute Driver Script安装并激活images、execute-driver插件修正受端点参数变更影响的客户端调用signalStrength、text等如直接 import 了 Appium 内部包更新为appium/*命名。按上述清单完成改造后即可平稳切换到 Appium 2享受驱动独立发版、配置文件、第三方扩展生态等新能力带来的效率提升。【免费下载链接】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），仅供参考 Appium 1 迁移到 Appium 2 完整指南：破坏性变更、驱动/插件生态与配置迁移实战
Appium 1 迁移到 Appium 2 完整指南破坏性变更、驱动/插件生态与配置迁移实战【免费下载链接】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 1 并计划迁移到 Appium 2 的测试开发人员与测试基础设施维护者。Appium 2 是该框架近五年来最重要的一次架构级发布其核心思路不再局限于某个平台的具体自动化行为而是将 Appium 重塑为以 W3C WebDriver 协议为核心、由独立驱动Driver与插件Plugin扩展构成的自动化生态。读完本文你将系统掌握 Appium 1 到 Appium 2 的全部破坏性变更Drivers 独立安装与更新、APPIUM_HOME路径变化、默认 base path 变更、appium:能力前缀、旧协议废弃、CLI 选项变化等以及配置文件、第三方扩展、云服务商适配等新特性的实战用法可直接据此改造现有测试套件与 CI 环境。Appium 2从单体服务器到扩展生态Appium 2 的定位与 Appium 1 有本质区别。它并不聚焦于改变某个特定平台的自动化行为而是重新构想了 Appium 的组织形态见 迁移指南原文核心 Appium 模块只保留与平台无关的功能会话管理、HTTP 服务、协议解析、日志等通用能力。特定平台的自动化功能被拆分到独立的 driver 模块例如 iOS 的 XCUITest、Android 的 UiAutomator2各自独立发布、独立升级。用于修改/扩展 Appium 行为的功能被拆分到独立的 plugin 模块例如图片查找、Execute Driver Script 等高级特性。与此同时Appium 项目借此次大版本重构的机会清理了大量陈旧或已废弃的功能。特别提醒由于这是一次重大架构变更官方不推荐直接对 Appium 1 安装执行原地升级正确的做法是先卸载 Appium 1再全新安装 Appium 2。破坏性变更清单与迁移动作以下按原文档顺序逐项列出破坏性变更并为每一项给出动作清单Actions Needed与源码级佐证。Drivers 改为独立安装安装 Appium 1 时所有官方驱动会随主服务器一起装好而 Appium 2 采用模块化结构默认只安装核心服务器不附带任何驱动。安装驱动的途径有三条安装 Appium 时通过--drivers标志顺带安装npm i -g appium --driversxcuitest,uiautomator2使用 Appium Extension CLIappium driver install uiautomator2使用 Appium2.6新增的 Appium Setup CLI 命令按预设一键安装整组扩展appium setup mobile动作清单安装 Appium 2 时务必使用上述任一方式安装你需要的驱动否则服务器将不认识任何设备。关于第 3 种方式仓库中的 setup.md 给出了完整预设说明appium setup mobile会安装移动测试所需的uiautomator2、xcuitest仅 macOS、espresso驱动以及images、inspector插件mobile可省略直接运行appium setup此外还有browsersafari/gecko/chromium 驱动 images/inspector 插件、desktopmac2/windows 驱动 images/inspector 插件与reset清空 Appium 主目录下全部扩展及 manifest可用于修复升级失败导致的启动配置问题等子命令。Driver 安装路径变更APPIUM_HOMEAppium 1 中驱动作为主服务器的依赖装在/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_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent。这一设计在源码中得到印证extension-config.ts 中扩展的安装根目录被解析为path.join(this.appiumHome, node_modules, ...)即$APPIUM_HOME/node_modules/pkgName并维护一份位于$APPIUM_HOME/node_modules/.cache/appium/extensions.yaml的扩展清单manifest。更多细节可参考 Managing Drivers and Plugins 指南该指南还展示了如何利用APPIUM_HOME在同一台机器上并行管理不同版本的同一驱动APPIUM_HOME/path/to/home1 appium driver install xcuitest4.11.1 APPIUM_HOME/path/to/home2 appium driver install xcuitest4.11.2 APPIUM_HOME/path/to/home1 appium # 使用 xcuitest 驱动 4.11.1 APPIUM_HOME/path/to/home2 appium # 使用 xcuitest 驱动 4.11.2动作清单如果你的代码中硬编码了 Appium 驱动文件路径请改用APPIUM_HOME环境变量动态拼接。Drivers 可独立更新Appium 1 中驱动更新只能等新版本 Appium 发布后整体升级Appium 2 中服务器与驱动是相互独立的 npm 包可各自独立发版无需等待服务器新版本即可安装最新驱动。检查更新使用 Appium Extension CLIappium driver list --updates有可用更新时对指定驱动执行更新appium driver update xcuitest升级 Appium 服务器本身与以往相同npm update -g appium但由于驱动不再捆绑在服务器包中这一过程明显更快。需要注意Extension CLI 的update子命令默认只升级 minor 与 patch 版本以避免破坏性变更如需升级大版本需加--unsafe如appium driver update uiautomator2 --unsafeappium plugin update installed则可一次更新全部已安装插件。动作清单请统一使用 Appium Extension CLI 来管理你的驱动。废弃包不再受支持Appium 1 生态中存在一批已被替代的驱动、客户端等包Appium 2 不再支持它们官方给出的替换对照如下Appium 1 包Appium 2 中的替代iOS DriverXCUITest DriverUiAutomator DriverUiAutomator2wdClientWebdriverIO ClientAppium DesktopAppium Inspector动作清单如果你正在使用上表所列的任一包请迁移到推荐替代品。默认服务器 Base Path 变更Appium 1 的默认服务器地址是http://localhost:4723/wd/hub其中/wd/hub是源自 Selenium 1 的历史遗留约定。Appium 2 将默认 base path 改为/因此默认地址变为http://localhost:4723/。如需沿用旧地址可通过--base-path/wd/hub命令行参数 启动服务器对应--base-path,-pa参数默认值为。该参数在源码中贯穿服务器启动链路它会被归一化后用于路由前缀见 main-helpers.ts 中的normalizeBasePath并参与 BiDi WebSocket 地址拼装与 Selenium Grid 节点注册 URL 的构造见 appium.ts 与 grid-v3-register.ts 中http://${addr}:${port}${basePath}的拼接逻辑。动作清单在测试脚本中把目标服务器 URL 的 base path 从/wd/hub改为/或者用--base-path/wd/hub保留旧路径。不再支持端口 0Appium 1 支持--port 0其效果是让服务器启动在一个随机空闲端口上Appium 2 取消了这一特性端口值必须是1或更大。若仍需随机端口需自行在启动前探测并指定一个可用端口。服务器相关参数可参见 server.md默认端口4723。动作清单若你正在以--port 0启动 Appium请改为1或更大的具体端口号。Driver 专属 CLI 选项发生变化Appium 1 中特定驱动专属的命令行选项全部挂在主服务器上例如用--chromedriver-executable为 UiAutomator2 驱动指定 Chromedriver 位置。Appium 2 中所有驱动专属 CLI 选项都移到了驱动自身但传递方式因驱动而异部分选项仍可作为 CLI 标志传递只是改名为带驱动前缀的形式appium --webdriveragent-port5000 # Appium 1 appium --driver-xcuitest-webdriveragent-port5000 # Appium 2部分选项改为通过环境变量传递appium --chromedriver-version100 # Appium 1 CHROMEDRIVER_VERSION100 appium # Appium 2部分选项改为通过 capabilities 传递appium --chromedriver-executable/path/to/chromedriver # Appium 1 {appium:chromedriverExecutable: /path/to/chromedriver} # Appium 2动作清单如果你使用了驱动专属 CLI 选项请查阅对应驱动文档确认在 Appium 2 中应如何传递CLI 标志 / 环境变量 / capability 三选一。部分 CLI 选项不再接受文件路径Appium 1 中以下四个服务器选项支持传入文件路径Appium 会自动读取文件内容作为选项值--nodeconfig--default-capabilities--allow-insecure--deny-insecureAppium 2 不再解析这些选项的文件路径内容改为两种指定方式直接在命令行以字符串形式传递--nodeconfig/--default-capabilitiesJSON 字符串--allow-insecure/--deny-insecure逗号分隔列表放在 Appium 配置文件 中此时以原生类型书写例如--use-plugins在配置文件里就是数组[my-plugin, some-other-plugin]。动作清单如果你曾以文件路径形式使用上述选项请改为直接传值或通过配置文件提供。旧协议被移除Appium 的 API 基于 W3C WebDriver 协议并已支持多年。在它成为 Web 标准之前业界先后使用 JSON Wire ProtocolJSONWP与 Mobile JSON Wire ProtocolMJSONWP。Appium 1 同时支持这三种协议以兼容旧版 Selenium/Appium 客户端Appium 2 移除了 JSONWP/MJSONWP 支持仅兼容 W3C WebDriver 协议。动作清单确保你使用的是兼容 W3C WebDriver 协议的 Selenium/Appium 客户端。Capabilities 必须使用 Vendor PrefixAppium 1 中创建会话需指定若干 desired capabilitiesAppium 2 延续了这一行为desired capabilities 现统称 capabilities但按照 W3C WebDriver 规范所有非标准 capability 都必须带 vendor prefix。标准 capability 由 W3C 规范定义常见的有browserName、platformName等Capabilities Guide 中列出的标准项还包括browserVersion。其余 capability 必须以供应商名加冒号开头如moz:、goog:。由于 Appium 绝大多数 capability 超出标准范围它们都必须带appium:前缀deviceName # Appium 1 appium:deviceName # Appium 2这一要求是否构成破坏性变更取决于你的测试套件较新版本的官方 Appium 客户端与 Appium Inspector 会自动为非标准 capability 补上appium:前缀部分云 Appium 服务商也会自动处理。为避免逐个加前缀显得冗余可把 Appium 专属 capability 统一收进单个对象型 capabilityappium:options默认写法{ platformName: iOS, browserName: Safari, appium:platformVersion: 14.4, appium:deviceName: iPhone 11, appium:automationName: XCUITest }使用appium:options的写法{ platformName: iOS, browserName: Safari, appium:options: { platformVersion: 14.4, deviceName: iPhone 11, automationName: XCUITest } }警告appium:options对象内的 capability 会覆盖同名的外部 capability即内层优先且各云服务商对appium:options语法的支持程度可能不同。能力capabilities是启动 Appium 会话的核心参数在会话生命周期内不可变更驱动若需在会话中动态调整行为应使用 Settings API。更多能力说明见 Capabilities Guide基础驱动支持的全部能力见 会话能力参考。动作清单为测试中所有 Appium 专属 capability 加上appium:前缀或统一放入appium:options对象。高级功能迁移到插件Appium 2 的设计目标之一是把非核心功能抽取为名为 plugins 的特殊扩展。Appium 1 中有两项功能已迁出并不再随 Appium 2 内置功能插件名称仓库内对应包图像相关功能图像比较、按图搜索等imagespackages/images-pluginExecute Driver Script 功能execute-driverpackages/execute-driver-plugin动作清单如果你在 Appium 1 中使用过图像功能或 Execute Driver Script请先安装对应插件appium plugin install images appium plugin install execute-driver然后启动服务器时必须激活插件appium --use-pluginsimages,execute-driver--use-plugins默认不激活任何插件设为[all]可激活全部已安装插件对应参数详见 server.md。端点参数变更Appium 1 的部分服务器端点曾接受旧参数或无用参数Appium 2 移除了这些参数。变更清单如下✗ 为不再接受的参数✓ 为 Appium 2 继续接受的参数POST /session/:sessionId/appium/device/gsm_signal✗signalStrengh拼写错误的历史参数✓signalStrengthPOST /session/:sessionId/appium/element/:elementId/value✗value✓textPOST /session/:sessionId/appium/element/:elementId/replace_value✗value✓text动作清单查阅你的 Appium 客户端文档中调用这些端点的方法并修改代码只使用被接受的参数。内部包重命名Appium 1 中内部依赖包各自位于独立仓库Appium 2 改为 monorepo 结构并重命名了其中大量包例如appium-base-driver # Appium 1 appium/base-driver # Appium 2本仓库即采用该 monorepo 结构packages/目录下可以看到 appium/base-driver、appium/base-plugin、appium/support、appium/types、appium/schema 等以appium/为作用域的包。动作清单如果你没有直接在代码中 import Appium 的包无需任何操作如果有请更新包名。Appium 2 的主要新特性除破坏性变更外Appium 2 还带来以下值得利用的新能力第三方驱动与插件Appium 2 不再局限于官方或 Appium 团队已知的驱动/插件——开发者可以自行编写驱动或插件并通过 Extension CLI 从npm、git、GitHub 甚至本地文件系统安装。install子命令的--source选项控制安装来源取值git、github、local、npm并相应改变install-spec的格式sourceinstall-spec格式无官方扩展短名可带 npm install 支持的版本/tag 修饰git扩展的 Git URLgithub扩展的 GitHub 仓库 URLlocal包含package.json的本地路径npmnpm 包名可带版本/tag 修饰典型示例appium driver install xcuitest9.0.0 appium driver install appium/fake-driverbeta --sourcenpm appium plugin install /path/to/my/plugin --sourcelocal appium driver install github-url --sourcegithub --packageappium-xcuitest-driver appium driver install git://git-url.git#specific-branch --sourcegit --packageappium-xcuitest-driver本仓库就是扩展开发的一手参考packages/fake-driver与packages/fake-plugin提供了最小可运行的驱动/插件实现与对应 schema 校验fake-driver-schema.ts、fake-plugin-schema.tspackages/driver-test-support与packages/plugin-test-support则提供了编写驱动/插件测试的支撑设施。Extension CLI 还支持list含--installed、--updates、--verbose、--json、run运行扩展自带脚本如appium driver run uiautomator2 reset、doctor运行扩展的医生检查如appium driver doctor uiautomator2与uninstall等子命令详见 extensions.md。配置文件Appium 2 在命令行参数之外新增了配置文件支持几乎所有 Appium 1 中必须通过 CLI 指定的选项现在都能写进配置文件。格式支持 JSON、YAML、JS/CJS注意ESM 格式暂不支持。配置文件以server为根属性参数为其子属性CLI 中需要逗号分隔字符串、JSON 字符串或文件路径的参数在配置文件中使用原生类型。{ server: { use-plugins: [my-plugin, some-other-plugin] } }驱动与插件专属配置分别位于server.driver与server.plugin属性下键名与扩展包名对应且全部属性区分大小写并使用 kebab-case如callback-port合法callbackPort不合法{ server: { driver: { xcuitest: { webkit-debug-proxy-port: 5400 } } } }上述配置等价于 CLI 参数--driver-xcuitest-webkit-debug-proxy-port。Appium 会从当前工作目录向上逐级搜索配置文件支持.appiumrc.json推荐、.appiumrc.yaml/.yml、.appiumrc.js/.cjs、appium.config.js/.cjs、.appiumrc按 JSON 解析以及 Node.js 项目中package.json里的appium属性也可用appium --config /path/to/config/file指定自定义位置。仓库内提供了三种格式的完整示例appium.config.sample.json、appium.config.sample.yaml、appium.config.sample.js以及配置的 JSON Schema 定义appium-config.schema.json。完整说明见 Config File Guide。注意CLI 参数的优先级高于配置文件二者同时设置时以 CLI 为准。给云服务商的特别提示上述内容大多面向 Appium 终端用户或开发者但 Appium 2 的部分架构变化对各类 Appium 服务提供方云厂商而言同样是破坏性变更——归根结底Appium 服务器的维护者负责安装并向终端用户暴露各类驱动与插件。云厂商需要仔细阅读并理解社区对云服务商 capability 的建议相关讨论集中在 Capabilities Guide 的云服务商章节以兼容行业通行的方式支撑用户需求例如采用$cloud:appiumOptions风格的 capability其中$cloud应替换为各家自己的 vendor 前缀用version、automationVersion、automation、plugins等键描述所需的服务器版本、驱动版本、自定义驱动与插件清单。迁移检查清单完成 Appium 1 → 2 迁移前建议逐项核对卸载 Appium 1全新安装 Appium 2并同时安装所需驱动--drivers/appium driver install/appium setup mobile三选一更新任何硬编码的驱动文件路径改用APPIUM_HOME环境变量改用 Extension CLI 管理驱动更新appium driver list --updates、appium driver update替换已废弃的包iOS Driver→XCUITest、UiAutomator Driver→UiAutomator2、wd→WebdriverIO、Appium Desktop→Appium Inspector测试脚本中服务器 URL 的 base path 改为/或启动时加--base-path/wd/hub去掉--port 0显式使用1及以上端口按各驱动文档迁移驱动专属 CLI 选项CLI 标志 / 环境变量 / capability 三种形态不再向--nodeconfig等四个选项传文件路径改为直接传值或写入配置文件确认客户端兼容 W3C WebDriver 协议为所有非标准 capability 添加appium:前缀或用appium:options归组若使用图像功能或 Execute Driver Script安装并激活images、execute-driver插件修正受端点参数变更影响的客户端调用signalStrength、text等如直接 import 了 Appium 内部包更新为appium/*命名。按上述清单完成改造后即可平稳切换到 Appium 2享受驱动独立发版、配置文件、第三方扩展生态等新能力带来的效率提升。【免费下载链接】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），仅供参考