Appium 2 迁移完全指南从 Appium 1 平滑升级的破坏性变更清单与实战方案【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appiumAppium 2 是该框架五年来最大的一次架构级发布它不再执着于改变某个特定平台的自动化行为而是把整个项目重塑为核心服务器 驱动Driver 插件Plugin的自动化工具生态。本文基于本仓库的官方迁移文档整理逐条梳理 Appium 1 升级到 Appium 2 时遇到的全部破坏性变更、对应的修复动作以及迁移后值得立即使用的核心新特性并辅以仓库源码层面的实现证据帮助你在升级前完成完整评估、在升级中按清单逐项改造环境与测试代码最终平稳落地 Appium 2。迁移前的准备为什么不要直接升级Appium 2 是重大架构变更官方文档明确给出建议不要直接对 Appium 1 的安装执行就地升级而是先卸载 Appium 1再安装 Appium 2。原因在于两者的包结构完全不同——Appium 1 把全部驱动捆绑在服务器包内而 Appium 2 采用模块化设计核心 Appium 模块只保留与平台无关的功能特定平台的自动化能力被拆分为独立的driver驱动模块用于改变或扩展 Appium 行为的能力被拆分为独立的plugin插件模块。同时Appium 2 借此机会清理了大量老旧、废弃的功能与依赖。从本仓库的目录结构可以直观看到这套模块化的落地packages 目录下既有承载核心的appium、base-driver、base-plugin、schema、support等基础设施包也有fake-driver、images-plugin、execute-driver-plugin、storage-plugin、universal-xml-plugin等驱动与插件包——这正是生态化结构在源码层面的直接体现。一、破坏性变更逐条清单1. 驱动不再随服务器捆绑安装安装 Appium 1 时所有官方驱动会一并装好而 Appium 2 默认只安装核心服务器不附带任何驱动需要你主动安装所需驱动。官方提供了三种安装途径# 方式一安装 Appium 时通过 --drivers 标志一并安装指定驱动 npm i -g appium --driversxcuitest,uiautomator2 # 方式二使用 Extension CLI 单独安装 appium driver install uiautomator2 # 方式三使用 Setup CLI 预设命令Appium 2.6 新增 appium setup mobile其中短名如uiautomator2、xcuitest与真实 npm 包名的对应关系定义在 packages/appium/lib/constants.ts 中KNOWN_DRIVERS聚合了移动端uiautomator2、xcuitest、espresso、桌面端mac2、windows与浏览器端safari、gecko、chromium驱动KNOWN_PLUGINS则收录了execute-driver、images、inspector、relaxed-caps、storage、universal-xml等官方插件。也就是说appium driver install uiautomator2实际上等价于安装appium-uiautomator2-driver这个 npm 包。appium setup mobile这类预设命令在 packages/appium/lib/cli/setup-command.ts 中实现setup下分mobile、desktop、browser、reset四个子命令默认插件为images与inspector并且会做平台适配——xcuitest、safari、mac2仅在 macOS 主机上安装windows仅在 Windows 主机上安装。需要执行的动作安装 Appium 2 时务必使用上述三种方式之一安装你所需的驱动。驱动与插件的完整管理方式安装、更新、卸载、运行脚本、doctor 检查请参考 Managing Drivers and Plugins 指南 与 Extension CLI 参考。2. 驱动的安装路径发生了变化Appium 1 中驱动是主服务器的依赖安装路径固定为/path/to/appium/node_modules例如手动构建 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-webdriveragentAPPIUM_HOME的妙处在于可以灵活切换多套扩展集合。例如你想让同一驱动在不同版本间共存可以参考 managing-exts.md 中的做法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已安装扩展的记录文件manifest存放在$APPIUM_HOME/node_modules/.cache/appium/extensions.yaml这一点与 packages/appium/lib/constants.ts 中定义的缓存目录常量CACHE_DIR_RELATIVE_PATHnode_modules/.cache/appium相互印证。需要执行的动作如果代码里写死了指向 Appium 驱动文件的绝对路径请改用APPIUM_HOME环境变量推导。3. 驱动与服务器可以各自独立更新Appium 1 中想获得驱动更新必须等待新版本 Appium 发布然后整体升级服务器Appium 2 中驱动与服务器是独立 npm 包可以各自发布、独立更新——你不再需要等待新的服务器版本即可立刻安装最新驱动。检查驱动是否有更新使用 Extension CLIappium driver list --updates若有可用更新对指定驱动执行update命令appium driver update xcuitest服务器本身的更新方式与以前一致但由于驱动不再捆绑在服务器包中升级过程会快很多npm update -g appium需要执行的动作务必使用 Extension CLI 来管理你的驱动。补充说明appium driver update默认只升级 minor/patch 版本以规避破坏性变更如需升级到新的主版本major需要显式加--unsafe参数appium plugin update installed可以一次性更新所有已安装插件。4. 已废弃的软件包不再被支持Appium 1 生态中有些驱动、客户端等包早已被新包取代Appium 2 不再为这些包提供支持官方建议迁移到以下替代品Appium 1 包Appium 2 中的替代品iOS DriverXCUITest DriverUiAutomator DriverUiAutomator2 DriverwdClientWebdriverIO ClientAppium DesktopAppium Inspector需要执行的动作如果你正在使用上述任一软件包请迁移到官方推荐的替代方案。仓库内 Ecosystem 文档 列出了当前生态中可用的驱动与客户端。5. 服务器默认基础路径base path变更Appium 1 的默认服务器 URL 是http://localhost:4723/wd/hub其中/wd/hub是源自 Selenium 1 的历史遗留约定。Appium 2 将默认基础路径改为/因此默认服务器 URL 变为http://localhost:4723/如果你希望保留 Appium 1 的行为可以在启动时显式传入--base-path/wd/hub参见 服务器 CLI 参考。需要执行的动作在测试脚本中把目标服务器 URL 的基础路径从/wd/hub改为/或者通过--base-path/wd/hub命令行参数沿用旧路径。从源码看base path 不只是URL 前缀这么简单在 packages/appium/lib/appium.ts 中WebDriver BiDi 的 WebSocket 地址也是由address、port、basePath拼接而成的在 packages/appium/lib/bootstrap/grid-v3-register.ts 中注册到 Selenium Grid 的节点 URL 同样是http://${addr}:${port}${basePath}的形式。也就是说修改 base path 会影响所有以此为前缀的 HTTP 路由与 WebSocket 端点改造时务必全局替换。6. 服务器端口 0 不再被支持Appium 1 支持--port 0其效果是让服务器自动选择一个空闲随机端口。Appium 2 不再允许端口为 0端口值必须大于等于 1。如果你确实需要随机端口必须在启动服务器之前自行处理例如在脚本中探测空闲端口再传入。需要执行的动作如果代码/脚本中使用--port 0启动 Appium请把端口改为1或更大的值。7. 驱动特有的 CLI 选项全部搬家Appium 1 中特定驱动专用的命令行选项都挂在主 Appium 服务器上例如--chromedriver-executable可以用来为 UiAutomator2 驱动指定 Chromedriver 的位置。Appium 2 中这些选项被移回驱动自身但不同驱动接收这些选项的方式不同主要有三种仍然作为 CLI 标志但加上了--driver-名字-前缀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 传入。8. 部分 CLI 选项不再接受文件路径Appium 1 中以下四个服务器选项支持传入文件路径Appium 会自动解析文件内容作为选项值--nodeconfig--default-capabilities--allow-insecure--deny-insecureAppium 2 不再解析传入这些选项的文件路径而是提供了两种指定方式直接在命令行传字符串--nodeconfig/--default-capabilities传 JSON 字符串--allow-insecure/--deny-insecure传逗号分隔的列表。写入 Appium 配置文件详见 Config File 指南。需要执行的动作如果你在使用上述选项时传的是文件路径请改为直接传递文件内容字符串或把内容放入 Appium 配置文件。9. 旧协议 JSONWP / MJSONWP 被移除Appium 的 API 长期基于 W3C WebDriver 协议。在 W3C 协议成为标准之前业界先后使用过 JSON Wire ProtocolJSONWP和 Mobile JSON Wire ProtocolMJSONWP。Appium 1 同时兼容这三种协议以便旧版 Selenium/Appium 客户端与新服务器通信Appium 2 移除了 JSONWP/MJSONWP 支持只兼容 W3C WebDriver 协议。需要执行的动作确保你使用的 Selenium/Appium 客户端兼容 W3C WebDriver 协议。10. Capabilities 必须带厂商前缀vendor prefixAppium 1 中创建会话时要指定 desired capabilities例如要使用哪个驱动。Appium 2 延续这一行为现在直接叫 capabilities但作为 W3C WebDriver 协议规范的一部分所有非标准 capability 必须使用厂商前缀。W3C 标准能力standard capabilities很少常见的就是browserName、platformName等几个。其余能力必须以厂商名 冒号开头例如moz:、goog:。Appium 的大部分能力超出了 W3C 标准集因此除个别特例外都必须带appium:前缀deviceName # Appium 1 appium:deviceName # Appium 2这一要求对现有测试套件是否构成破坏取决于你的客户端较新版本的官方 Appium 客户端和 Appium Inspector 会自动为所有非标准能力添加appium:前缀部分云端 Appium 服务商也是如此。关于标准能力与 Appium 扩展能力的完整对照可参见 Session Capabilities 指南。当一条会话请求包含大量 Appium 特有能力时逐个加前缀会很啰嗦此时可以把它们统一塞进一个appium: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对象内与对象外同名的能力以对象内的值为准会覆盖外部值不同云服务商对appium:options语法的支持程度可能不一致。需要执行的动作为测试中所有 Appium 特有能力添加appium:前缀或者把它们包裹进appium:options对象。11. 高级功能被抽离为插件Appium 2 的设计目标之一就是把非核心功能抽离为名为plugin的扩展参见 插件生态文档。Appium 1 中的两个功能被移到插件中不再随 Appium 2 捆绑功能插件名图像相关功能图像比较、按图查找等imagesExecute Driver Script在驱动脚本中执行命令功能execute-driver如果你在 Appium 1 中使用了这两类功能迁移步骤为先安装插件再在启动服务器时激活插件appium plugin install images appium plugin install execute-driver appium --use-pluginsimages,execute-driver这两个插件在本仓库中均有独立实现packages/images-plugin内含图像查找finder.ts、图像比较compare.ts、图像元素image-element.ts等模块和 packages/execute-driver-plugin内含子进程执行execute-child.ts、VM 宿主绑定vm-host-binding.ts等模块可以直接阅读其源码了解能力边界。12. 部分服务器端点不再接受旧参数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 客户端文档中调用这些端点的方法调整代码只使用被接受的参数名。13. 内部依赖包被重命名Appium 1 的内部依赖包各自拥有独立仓库Appium 2 改为 monorepo 结构因此大量包被重命名例如appium-base-driver # Appium 1 appium/base-driver # Appium 2本仓库的 packages 目录正是这一 monorepo 结构的体现base-driver、base-plugin、schema、support、types、logger等包全部以appium/*命名空间组织。需要执行的动作如果你的代码没有直接 import Appium 包则无需任何改动如果有请更新所有 Appium 包的导入名称。二、Appium 2 带来的主要新功能1. 第三方驱动与插件你不再局限于官方驱动/插件甚至不限于 Appium 团队已知的扩展开发者可以自行创建自定义驱动或插件并通过 Extension CLI 从npm、git、GitHub、甚至本地文件系统安装。安装时可用--source指定来源常见的组合方式包括# 官方短名 版本 appium driver install xcuitest9.0.0 # 从 npm 安装指定包 appium driver install appium/fake-driverbeta --sourcenpm # 从 GitHub 仓库安装需配合 --package 指定包名 appium driver install https://github.com/appium/appium-xcuitest-driver --sourcegithub --packageappium-xcuitest-driver # 从本地文件系统安装指向含 package.json 的目录 appium plugin install /path/to/my/plugin --sourcelocal想要开发自己的驱动或插件请参考 Developing 文档 与 驱动安装路径约束 中关于APPIUM_HOME的说明。另外值得注意的是一个合格的驱动必须在package.json的appium字段中暴露driverName、automationName、platformNames、mainClass四个字段——这个校验逻辑在 packages/appium/lib/cli/driver-command.ts 的validateExtensionFields中实现缺任一字段都会导致安装失败并提示缺失项。2. 配置文件Config FileAppium 2 在命令行参数之外新增了对配置文件的支持。几乎 Appium 1 中必须在 CLI 上指定的选项现在都可以写进配置文件。配置文件支持 JSON、JS、YAML 三种格式。推荐命名为.appiumrc.json、.appiumrc.yaml、.appiumrc.js等完整清单见 Config File 指南Appium 会从当前工作目录向上逐级自动查找也可用appium --config /path/to/config显式指定。配置文件的结构是根级server对象所有参数作为其子属性且直接使用原生类型——例如 CLI 中要求逗号分隔列表的--use-plugins在配置文件中就是一个数组{ server: { use-plugins: [images, execute-driver] } }驱动和插件自身的配置分别放在server.driver与server.plugin下每个扩展一个命名属性属性名使用 kebab-case且区分大小写{ server: { driver: { xcuitest: { webkit-debug-proxy-port: 5400 } } } }上面的配置等价于 CLI 参数--driver-xcuitest-webkit-debug-proxy-port 5400——注意它正好对应前面破坏性变更第 7 条中提到的驱动特有选项的新命名规则。同时请记住CLI 参数的优先级高于配置文件两者同时设置时以 CLI 为准。仓库的 sample-code 目录 提供了 JSON、YAML、JS 三种格式的完整示例文件appium.config.sample.json、appium.config.sample.yaml、appium.config.sample.js可以直接作为模板使用。3. 使用 npm 直接管理驱动与插件如果你本来就在用 npm 管理 Node.js 项目还有一条更贴合工程实践的扩展管理路线把驱动、插件直接声明为项目的依赖Appium 启动时会自动识别。前提是当前目录处于某个 npm 包中、appium出现在该包的依赖dev/prod/peer里、且未显式设置APPIUM_HOME。例如{ devDependencies: { appium: ^2.0.0, appium-xcuitest-driver: ^4.11.1 } }然后在项目内执行npx appiumAppium 就会检测到项目依赖关系并加载对应的驱动。这种方式仅推荐给已经在用 npm 管理项目的团队否则还是优先使用 Extension CLI必要时通过APPIUM_HOME调整扩展的存储位置。详见 Managing Drivers and Plugins 指南。三、面向云服务提供商的特别说明以上内容大多适用于 Appium 终端用户或普通开发者但 Appium 2 的部分架构变更对各类 Appium 服务提供商云测平台而言同样是破坏性的。归根结底Appium 服务器的维护者负责安装并向终端用户暴露各种驱动与插件——这意味着云平台需要用上文的方式预先安装并持续更新维护驱动与插件集合兼容 W3C WebDriver 协议、正确处理appium:前缀与appium:options语法不同云平台对appium:options的支持程度可能不同规划好APPIUM_HOME下的多版本、多租户扩展管理方案适配默认 base path 由/wd/hub变为/的变化。官方建议云服务商认真阅读并理解 Session Capabilities 指南中的云服务商能力建议以行业兼容的方式满足用户需求。四、迁移行动清单速查把全文要点汇总成一张可逐项勾选的清单供升级时对照执行先卸载 Appium 1再安装 Appium 2不要原地升级通过--drivers、appium driver install或appium setup mobile安装所需驱动代码中引用驱动文件路径的地方改用APPIUM_HOME环境变量推导用appium driver list --updates与appium driver update name取代等服务器发版的更新习惯已废弃的 iOS Driver / UiAutomator /wd/ Appium Desktop 迁移到官方替代品测试脚本中服务器 URL 基础路径由/wd/hub改为/或启动时加--base-path/wd/hub将--port 0改为1及以上的具体端口随机端口自行探测排查驱动特有 CLI 选项按驱动文档改为--driver-*前缀标志、环境变量或 capability--nodeconfig、--default-capabilities、--allow-insecure、--deny-insecure不再接受文件路径改为直接传字符串或写进配置文件客户端升级到兼容 W3C WebDriver 协议不再支持 JSONWP/MJSONWP的版本所有 Appium 特有 capability 加appium:前缀或用appium:options分组图像相关与 execute-driver 功能改为安装并激活images、execute-driver插件涉及gsm_signal、元素value/replace_value端点的代码改用新参数名若代码直接 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），仅供参考