Appium Session Capabilities 完全指南W3C 标准、appium:options、BiDi 与云厂商扩展【免费下载链接】appiumCross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol项目地址: https://gitcode.com/GitHub_Trending/ap/appium导读Capabilities能力参数是启动 Appium 会话的核心参数它们以键值对的形式描述你希望会话具备的种种特性——例如目标移动操作系统、设备版本、要启动的应用路径等。本文以 packages/appium/docs/ja/guides/caps.md 为骨架结合 base-driver 中能力解析的真实源码系统讲解 W3C 标准 capabilities 与 Appium 扩展 capabilities 的用法、appium:options分组技巧、WebDriver BiDi 协议的开启方式、always-match / first-match 机制以及面向云服务提供商的$cloud:appiumOptions建议规范。读完本文你将能正确构造会话请求、理解 Appium 服务器侧的能力处理链路并为在云环境中运行 Appium 2 设计合理的能力接口。什么是 Session CapabilitiesCapabilities 是用于启动 Appium 会话的核心参数它们描述了会话所需的各种特性——例如特定的移动操作系统、特定的设备版本。Capabilities 以键值对key-value pairs表示值可以是任意合法的 JSON 类型包括嵌套对象。最重要的一点是在会话生命周期内Capabilities 不可更改。如果你希望在会话进行中调整驱动行为请使用 Settings API其英文版位于 packages/appium/docs/en/guides/settings.md。Appium 中使用的 Capabilities 遵循 W3C WebDriver 规范即 WebDriver Classic中的同名概念。WebDriver 规范定义了一小组标准 capabilitiesCapability 名类型说明browserNamestring启动并自动化的浏览器名称browserVersionstring浏览器版本platformNamestring承载浏览器的平台类型如iOS、Android上述标准 capabilities 虽被 Appium 各驱动广泛使用却不足以描述 Appium 特有的功能例如使用哪个驱动、启动哪个应用。为此Appium 定义了属于自己的扩展 capabilitiesextension capabilities。从源码看base-driver 在 packages/base-driver/lib/basedriver/capabilities.ts 中维护了STANDARD_CAPS集合其内容比文档示例更完整export const STANDARD_CAPS Object.freeze( new Set([ browserName, browserVersion, platformName, acceptInsecureCerts, pageLoadStrategy, proxy, setWindowRect, timeouts, strictFileInteractability, unhandledPromptBehavior, userAgent, webSocketUrl, ]), );凡属于该集合的 capability 都不需要也不允许加appium:前缀isStandardCap()函数即用于区分标准 capability 与扩展 capability。常见的 Appium Capabilities按照 WebDriver 规范扩展 capabilities 必须包含一个命名空间前缀表示引入该 capability 的厂商且命名空间必须以冒号:结尾。Appium 的厂商前缀是appium:因此所有 Appium 特有的 capabilities 都必须携带此前缀。部分 Appium 客户端会自动添加前缀或在与特定接口配合时自动处理但显式写出前缀始终是更清晰、更稳妥的做法。几个常用但并非所有驱动都支持的 Appium 特有 capabilitiesCapability 名类型说明appium:automationNamestring要使用的 Appium 驱动名称appium:udidstring要自动化的特定设备的唯一设备标识符Unique Device Identifierappium:appstring可安装应用的路径base-driver 识别的通用 capabilities所有被 Appium base driver所有驱动都会继承它识别的 capabilities 完整清单见 Capabilities Reference英文版packages/appium/docs/en/reference/session/caps.md。这份参考文档将该清单分为三类必需RequiredCapabilities——Appium 服务器/base driver 明确要求所有会话提供Capability说明类型platformName承载应用或浏览器的平台类型stringappium:automationName要使用的 Appium 驱动名称string可选OptionalCapabilities——base driver 会使用但可选且有默认值Capability说明类型默认值webSocketUrl是否开启 WebDriver BiDi 协议支持booleanappium:eventTimings已弃用是否收集 Event Timings已弃用请改用getLogEvents端点booleanappium:newCommandTimeoutAppium 服务器在停止会话前等待客户端发送命令的秒数0表示禁用超时number60appium:printPageSourceOnFindFailure元素查找失败时是否获取页面源码并打印到 Appium 日志boolean仅校验ValidatedCapabilities——base driver 不会直接使用但会执行类型/取值校验Capability校验规则platformVersion必须是stringappium:app必须是string空值会被忽略appium:autoLaunch已弃用必须是booleanappium:autoWebview必须是booleanappium:fullReset必须是boolean与appium:noReset互斥appium:language必须是stringappium:locale必须是stringappium:orientation必须是LANDSCAPE或PORTRAITappium:noReset必须是boolean与appium:fullReset互斥appium:udid必须是string注意参考文档中的一条重要说明未在此列出的 capabilities 并不会被 Appium 拒绝它们会被直接转发给当前活动的 driver/plugin。这为驱动和插件定义自有 capabilities 提供了弹性。同时需要留意一个特殊约定标准 capabilities 不需要也不能加appium:前缀。base-driver 的stripAppiumPrefixes()见 packages/base-driver/lib/basedriver/capabilities.ts会检测“加了前缀的标准 capability”如appium:platformName发出警告并回退使用未加前缀的取值。驱动与插件可以扩展 capabilities虽然 base-driver 的公共 capability 集合较小但它可以被 Appium 的驱动和插件大幅扩展——驱动和插件可以也应该定义自己的 capabilities。务必查阅对应驱动/插件的文档来了解它们支持的 capabilities已知驱动的清单见 Ecosystem Drivers。驱动还可以对一组 capabilities 施加更复杂的组合约束。例如 XCUITest 驱动建议 capabilities 中至少包含browserName、appium:app、appium:bundleId之一否则它将无法自动安装或自动启动任何应用。每个驱动都会文档化自己如何解释这些 capabilities 及其他平台特定要求。构造 capabilities 与启动会话如何构造 capabilities 并启动会话取决于你使用的 Appium 客户端语言库。各客户端库的示例请参考 Ecosystem Clients 页面点击进入对应客户端文档即可。注意一旦 capabilities 被发送到服务器并成功创建会话它们就不可再更改。如果驱动支持在会话期间更新行为它会使用 Settings API 来实现这一目的。WebDriver BiDi 协议的支持除了标准的 WebDriver 协议现在称为 WebDriver ClassicAppium 还支持 WebDriver BiDi 协议。对 BiDi 的支持是**可选加入opt-in**的需要设置标准 capabilitywebSocketUrlCapability 名类型说明webSocketUrlboolean会话中是否启用 BiDi 协议客户端以布尔值发送从 Appium 服务器的实现看packages/appium/lib/appium.ts当请求的 caps 中包含webSocketUrl且内层驱动成功创建会话后Appium 会把上游驱动返回的webSocketUrl重写为该 Appium 服务器自身暴露的 BiDi WebSocket 地址ws[s]://host:port/basePath/session/sessionId再返回给客户端。也就是说客户端与 Appium 服务器之间、以及 Appium 服务器与内层驱动之间的 BiDi 连接可以被代理与统一管理相关实现见 packages/appium/lib/bidi-commands.ts。所有被 Appium base driver所有驱动都会继承支持的 BiDi 命令可在 BiDi Protocol API Reference 找到。与 WebDriver Classic 命令类似各 Appium 驱动和插件可以定义自己支持的标准与自定义 BiDi 命令请参考它们的文档。使用appium:options对 capabilities 分组如果测试中大量使用appium:前缀的 capabilities会产生大量重复。替代方案是把所有此类 capabilities 组合到单个appium:optionscapability 的对象值中此时对象内部的 capabilities 无需再写前缀。示例{ platformName: iOS, appium:options: { automationName: XCUITest, platformVersion: 16.0, app: /path/to/your.app, deviceName: iPhone 12, noReset: true } }当 capability 值本身是对象时不同语言构造它的语法各不相同具体示例请参考你所使用客户端的文档。appium:options的底层处理逻辑在 Appium 服务器侧appium:options并不会原样传给驱动而是会被“提升promote”到顶层。base-driver 的 promoteAppiumOptions / promoteAppiumOptionsForObject 实现了这一逻辑它读取appium:options对象对内部每个键自动补上appium:前缀若尚未加然后展开合并到顶层 caps若某键与顶层已有的 capability 重名会打印警告并以appium:options内部值为准。Appium 服务器在启动内层驱动前会先调用promoteAppiumOptions(w3cCapabilities)完成这一展开见 packages/appium/lib/appium.ts。相关的端到端测试覆盖见 packages/appium/test/e2e/driver.e2e.spec.ts测试通过alwaysMatch: {appium:options: {...}}的方式验证了会话能够正常创建。另外两点值得注意appium:options只能包含厂商特有vendor-specific的 capabilities——如果内部出现标准 capability 名如platformNamepromoteAppiumOptionsForObject会直接抛出SessionNotCreatedError如果你在appium:options内部与外部同时包含同名 capabilityappium:options内部的值优先服务器侧会打印覆盖警告。Always-Match 与 First-Match CapabilitiesW3C 规范允许客户端给 Appium 服务器一定的灵活性来决定响应新的会话请求时创建何种会话。这一机制通过 “always-match” 与 “first-match” 两组 capabilities 实现Always-match capabilities单一的一组 capabilities服务器必须满足其中每一个成员新的会话请求才能继续。First-match capabilities一组 capabilities 构成的数组。数组中每一组都会与 always-match capabilities 合并服务器能够处理的第一个组合将被用来启动会话。规范中 capabilities 的完整处理流程参见 W3C spec 的 Processing Capabilities 章节。实践建议直接使用显式 capabilities在实际使用中first-match 对于 Appium 并非必要也不推荐。相反我们建议直接定义你希望 Appium 服务器处理的那组显式 capabilities它们会被编码为 always-match capabilities而 first-match 数组保持为空。话虽如此Appium确实按照 W3C 规范理解 always-match 和 first-match capabilities因此如果你使用这些特性Appium 会按预期工作。定义 always-match / first-match capabilities 的方式因客户端库而异请参考你的客户端库文档中的示例。服务器侧如何解析与校验从 base-driver 源码看packages/base-driver/lib/basedriver/capabilities.ts 的parseCaps及processCapabilities服务器的处理步骤完全遵循 W3C 流程校验capabilities必须是 JSON 对象提取alwaysMatch默认空对象与firstMatch默认[{}]空数组会被宽容地补一个空对象并打警告对没有厂商前缀、且不属于标准 capabilities 的键直接抛InvalidArgumentError提示All non-standard capabilities should have a vendor prefix剥离appium:前缀stripAppiumPrefixes先以skipPresenceConstraint方式校验 always-match逐个校验 first-match 数组中的每个对象剔除不合法的项将 always-match 与第一个可用的 first-match 合并mergeCaps见同文件 L30-L56如果同一属性同时出现在两者中会抛错W3C 规则 4.4不允许覆盖找不到任何匹配组合时根据 firstMatch 数量抛出带全部错误信息的异常。内层驱动创建会话时最终通过processCapabilities(originalCaps, this._desiredCapConstraints, this.shouldValidateCaps)得到匹配的 caps 并加以校验见 packages/base-driver/lib/basedriver/driver.ts。例如noReset与fullReset同时为true会在会话创建阶段被直接拒绝driver.ts L322-L330。相关单元测试覆盖在 packages/base-driver/test/unit/basedriver/capabilities.spec.ts包含 first-match 依次尝试、重复属性报错、前缀校验等多种场景。面向云服务提供商的特殊建议警告本节并非面向 Appium 的最终用户而是面向构建 Appium 兼容云服务的开发者。在运营 Appium 云时你的用户可能希望定位各种独立版本的 Appium 驱动与插件。如何实现官方或第三方驱动/插件的发现、安装与可用性自然由各家服务提供商自行决定。但 Appium 团队提供了一些建议以保持整个行业的一致性。这些只是建议而非标准但采纳它们将帮助用户应对在云环境中使用 Appium 带来的复杂度。建议的 capabilities 设计除了标准的platformName、appium:deviceName、appium:automationName和appium:platformVersion我们建议采用 capability$cloud:appiumOptions其中标签$cloud不应被字面理解而应替换为你的厂商前缀例如 HeadSpin 用headspin、Sauce Labs 用sauce、BrowserStack 用browserstack这里仅举几例。$cloud:appiumOptions本身是一个 JSON 对象包含以下内部键Capability用途示例version用于托管和管理驱动的 Appium 服务器版本。若省略行为由服务商决定但建议提供最新官方版本2.0.0automationVersion应使用的驱动版本由appium:automationName指定1.55.2automation要使用的自定义驱动名称详见下文。将覆盖appium:automationName与$cloud:automationVersion{name: org/custom-driver, source: github, package: custom-driver}plugins应激活的插件列表及可能的插件版本详见下文[images, universal-xml]基本示例Appium 扩展驱动和插件拥有一组属性用于指明它们可以从何处安装。云服务商显然没有义务支持任意指定的扩展——因为这些可能是在托管环境中运行的不可信代码。在不支持任意扩展的情况下appium:automationName、$cloud:automationVersion与$cloud:appiumPlugins这些 capabilities 应该已经足够。请看以下表示一次会话 capabilities 的 JSON 对象{ platformName: iOS, appium:platformVersion: 14.4, appium:deviceName: iPhone 11, appium:app: Some-App.app.zip, appium:automationName: XCUITest, $cloud:appiumOptions: { version: 2.0.0, automationVersion: 3.52.0, plugins: [images] } }这组 capabilities 请求一个 Appium 2 服务器支持版本为3.52.0的 XCUITest 驱动并激活images插件。这组参数对云服务商来说很容易验证。云服务商当然可以对这组 capabilities 做任何处理包括即时下载 Appium 及驱动/插件包或在请求的版本不在受支持集合内、插件不受支持时报错等。结合appium:options的基本示例上面的示例看起来仍有点杂乱因此我们也建议云服务商支持前述的appium:optionscapability它可以把上一组 capabilities 改写为{ platformName: iOS, appium:options: { platformVersion: 14.4, deviceName: iPhone 11, app: Some-App.app.zip, automationName: XCUITest }, $cloud:appiumOptions: { version: 2.0.0, automationVersion: 3.52.0, plugins: [images] } }扩展对象Extension Objects部分服务商可能希望动态开放 Appium 2 CLI 的全部特性包括下载任意驱动和插件。为表示这些扩展可以定义特殊的 JSON “扩展对象extension objects”包含以下键name扩展的名称。从npm下载时为npm包名从git服务器或 GitHub 下载时为git或 GitHub 规范spec。version扩展的版本例如npm包版本或gitSHA。可选source指明扩展可以从哪里下载。建议支持以下值appium、npm、git、github。其中appium表示“Appium 自己的官方列表”并且应作为未包含此键时的默认值。可选package从git或 GitHub 下载扩展时必须同时提供扩展的npm包名。对非git来源此键可选。由于每个会话由单个驱动处理$cloud:appiumOptions的automation键可用一个扩展对象作为值来指明该驱动例如{ $cloud:appiumOptions: { automation: { name: githttps://some-git-host.com/custom-driver-project.git, version: some-git-sha, source: git, package: driver-npm-package-name } } }由于一个会话可以处理多个插件$cloud:appiumPlugins列表中的每个值也可以是扩展对象而非字符串以便请求特定版本{ $cloud:appiumOptions: { plugins: [{ name: images, version: 1.1.0 }, { name: my-github-org/my-custom-plugin, version: a83f2e, source: github, package: custom-plugin }] } }以上都是对建议的示例性说明。当然如何在前端/负载均衡器上实现这些 capabilities 的处理、执行任何错误检查、或实际运行支持最终用户请求的appium driver/appium pluginCLI 命令完全由服务提供商决定。本节只是就服务商如何设计其面向用户的 capabilities API 提出建议——该设计原则上应支持 Appium 自身在用户本地运行时所能提供的全部 capabilities。总结与延伸阅读会话不可变性Capabilities 在会话创建后不可修改会话内的动态行为调整应走 Settings API。前缀规则W3C 标准 capabilities 不加前缀Appium 特有 capabilities 必须带appium:前缀没有厂商前缀的非标准 capability 会被服务器拒绝。分组与优先级appium:options可以免去前缀重复书写其内部值在冲突时优先于顶层值但内部不得包含标准 capability。BiDi设置webSocketUrl: true即可按需启用 WebDriver BiDi 会话。云服务设计$cloud:appiumOptions及其version、automationVersion、automation、plugins键配合扩展对象可为云用户提供接近本地 Appium 的完整体验。进一步查阅完整 capabilities 清单见 Capabilities ReferenceBiDi 命令见 BiDi API Reference客户端示例见 Ecosystem Clients。【免费下载链接】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），仅供参考