会话功能

"功能" 是用于启动 Appium 会话的一组参数的名称。该集合中的信息描述了您希望会话具有的“功能”，例如，特定的移动操作系统或特定版本的设备。功能以键值对的形式表示，允许值为任何有效的 JSON 类型，包括其他对象。

W3C WebDriver 规范的关于功能的部分识别了一组 10 个标准功能，包括以下内容

功能名称	类型	描述
`browserName`	`字符串`	要启动和自动化的浏览器的名称
`browserVersion`	`字符串`	浏览器的特定版本
`platformName`	`字符串`	托管浏览器的平台类型

常见 Appium 功能¶

Appium 理解这些以浏览器为中心的功能，但引入了许多其他功能。根据 WebDriver 规范，任何非标准的“扩展功能”都必须包含一个命名空间前缀（表示引入该功能的供应商），以:结尾。Appium 的供应商前缀是appium:，因此任何特定于 Appium 的功能都必须包含此前缀。根据您使用的客户端，前缀可能会自动添加或与某些接口结合使用，但为了清晰起见，始终显式包含它是一个好习惯。

以下是所有全局认可的 Appium 功能的列表

信息

各个驱动程序和插件可以支持其他功能，因此请参阅其文档以获取特定功能名称的列表。某些驱动程序也可能不支持所有这些功能

功能	类型	必需？	描述
`platformName`	`字符串`	是	托管应用程序或浏览器的平台类型
`appium:automationName`	`字符串`	是	要使用的 Appium 驱动程序的名称
`browserName`	`字符串`	否	要启动和自动化的浏览器的名称，如果驱动程序支持 Web 浏览器作为特殊情况
`appium:app`	`字符串`	否	可安装应用程序的路径
`appium:deviceName`	`字符串`	否	要自动化的特定设备的名称，例如`iPhone 14`（目前仅对指定 iOS 模拟器真正有用，因为在其他情况下，通常建议通过`appium:udid` 功能使用特定设备 ID）。
`appium:platformVersion`	`字符串`	否	平台的版本，例如，对于 iOS，`16.0`
`appium:newCommandTimeout`	`数字`	否	Appium 服务器在决定客户端已消失且会话应关闭之前等待客户端发送命令的秒数
`appium:noReset`	`布尔值`	否	如果为真，则指示 Appium 驱动程序在会话启动和清理期间避免其通常的重置逻辑（默认值为`false`）
`appium:fullReset`	`布尔值`	否	如果为真，则指示 Appium 驱动程序使用其他步骤来增强其通常的重置逻辑，以确保最大程度的环境可重复性（默认值为`false`）
`appium:eventTimings`	`布尔值`	否	如果为真，则指示 Appium 驱动程序收集事件时间（默认值为`false`）
`appium:printPageSourceOnFindFailure`	`布尔值`	否	如果为真，则在查找元素的请求失败时收集页面源并将其打印到 Appium 日志（默认值为`false`）

某些驱动程序对功能组施加了更复杂的约束。例如，虽然appium:app 和browserName 功能在上面列出为可选，但如果您想使用特定应用程序启动会话，XCUITest 驱动程序要求在功能中包含至少一个appium:app、browserName 或appium:bundleId（否则它将不知道要安装和/或启动哪个应用程序，并且只会打开主屏幕上的会话）。每个驱动程序都会记录它如何解释这些功能以及任何其他特定于平台的要求。

注意

功能就像启动会话时使用的参数。发送功能并启动会话后，它们将无法更改。如果驱动程序支持在会话过程中更新其行为的各个方面，它将为此目的提供一个设置，而不是或除了功能之外。

每个 Appium 客户端都有自己的构建功能和启动会话的方法。有关在每个客户端库中执行此操作的示例，请转到生态系统页面，然后单击相应的客户端文档。

使用`appium:options` 对功能进行分组¶

如果您在测试中使用大量appium: 功能，它可能会变得有点重复。您可以将所有功能组合为单个appium:options 功能的对象值，在这种情况下，您不需要在对象内的功能上使用前缀。例如

{
    "platformName": "iOS",
    "appium:options": {
        "automationName": "XCUITest",
        "platformVersion": "16.0",
        "app": "/path/to/your.app",
        "deviceName": "iPhone 12",
        "noReset": true
    }
}

请注意，构建本身是对象的功能值因语言而异；请参阅您的客户端文档以获取有关如何实现此目的的更多示例。

警告

如果您在appium:options 内外都包含相同的功能，则appium:options 内部的值优先。

始终匹配和首次匹配功能¶

W3C 规范允许客户端在响应新的会话请求时，为 Appium 服务器提供一些创建会话类型的灵活性。这是通过“始终匹配”和“首次匹配”功能的概念实现的

始终匹配功能由一组功能组成，服务器必须满足该组中的每个成员才能使新的会话请求继续进行。
首次匹配功能由一组功能数组组成。每个集合都与始终匹配功能合并，服务器知道如何处理的第一个集合将是用于启动会话的集合。

注意

查看规范本身或总结版本以更深入地了解功能的处理方式。

实际上，使用首次匹配功能对于与 Appium 一起使用并不必要或推荐。相反，我们建议您定义您希望 Appium 服务器处理的显式功能集。这些将被编码为始终匹配功能，而首次匹配功能数组将为空。

话虽如此，Appium 确实理解 W3C 规范中定义的始终匹配和首次匹配功能，因此，如果您使用这些功能，Appium 将按预期工作。定义始终匹配和首次匹配功能的过程对于每个客户端库都是唯一的，因此请参阅您的客户端库的文档以查看其工作原理的示例。

云提供商的特殊说明¶

警告

本节不适用于 Appium 的最终用户；它适用于构建与 Appium 兼容的云服务的开发人员。

在管理 Appium 云时，您的用户可能希望针对各种独立版本的 Appium 驱动程序和插件。当然，每个服务提供商如何实现任何官方或第三方驱动程序或插件的发现、安装和可用性，这取决于他们自己。但 Appium 团队确实提供了一些建议，以确保整个行业的 consistency。这些只是建议，而不是标准，但采用它将帮助用户应对在云环境中使用 Appium 2 带来的复杂性增加。

建议的功能¶

除了标准的platformName、appium:deviceName、appium:automationName 和appium:platformVersion 之外，我们建议采用功能$cloud:appiumOptions，其中标签$cloud 不应被字面解释，而应替换为您的供应商前缀（因此对于 HeadSpin，它将是headspin，Sauce Labs 将是sauce，而 BrowserStack 将是browserstack，仅举几个例子）。$cloud:appiumOptions 功能本身将是一个 JSON 对象，具有以下内部键

功能	用法	示例
`版本`	用于托管和管理驱动程序的 Appium 服务器的版本。如果省略，行为将由提供商决定，但建议是提供最新的官方版本。	`2.0.0`
`automationVersion`	要使用的驱动程序版本（由 `appium:automationName` 指定）。	`1.55.2`
`automation`	要使用的自定义驱动程序名称（有关更多信息，请参见下文）。这将覆盖 `appium:automationName` 和 `$cloud:automationVersion`。	`{"name": "@org/custom-driver", "source": "github", "package": "custom-driver"}`
`plugins`	应激活的插件列表（以及可能插件的版本）（有关更多信息，请参见下文）。	`["images", "universal-xml"]`

基本示例¶

Appium 扩展（驱动程序和插件）具有一组属性，用于指定它们可以从何处安装。云提供商显然没有义务为任意指定的扩展提供支持，因为这些扩展可能代表在受管理环境中运行的不可信代码。在不支持任意扩展的情况下，appium:automationName、$cloud:automationVersion 和 $cloud:appiumPlugins 功能应该足够。请参见以下表示会话功能的 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"]
  }
}

这组功能请求支持 XCUITest 驱动程序（版本为 3.52.0）的 Appium 2+ 服务器，以及激活的 images 插件。这组功能易于云提供商验证。云提供商显然可以对这些功能做出任何反应，包括动态下载 Appium 以及驱动程序和插件包，或者如果请求的版本不在支持的集合中，或者如果插件不受支持，则出错，等等...

使用 `appium:options` 的基本示例¶

前面的示例看起来仍然有点混乱，因此我们当然也建议云提供商支持如上所述的 appium:options 功能，这可以将前面的功能集转换为以下内容

{
  "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"]
  }
}

扩展对象¶

一些服务提供商可能希望动态允许访问 Appium 2 CLI 的所有功能，包括下载任意驱动程序和插件。为了表示这些扩展，我们可以定义特殊的 JSON“扩展对象”，它们具有以下键

name：扩展的名称。这将是 npm 包名称（如果从 npm 下载），或者 git 或 GitHub 规范（如果从 git 服务器或 GitHub 下载）。
version：扩展的版本，例如 npm 包版本或 git SHA。
(可选) source：表示可以从何处下载扩展的符号。建议支持以下值：appium、npm、git、github。这里，appium 表示“Appium 自己的官方列表”，如果未包含此键，则应为默认值。
(可选) package：从 git 或 GitHub 下载扩展时，还必须提供扩展的 npm 包名称。对于非 git 源，这是可选的。

由于每个会话都由单个驱动程序处理，因此 $cloud:appiumOptions/$automation 功能可以与扩展对象值一起使用来表示此驱动程序，例如

{
    "$cloud:appiumOptions": {
        "automation": {
            "name": "git+https://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"
        }]
    }
}

这些是此处建议的说明性示例。当然，服务提供商有责任在其前端/负载均衡器处实现这些功能的处理，以执行任何错误检查，或者实际运行支持最终用户请求的任何 appium driver 或 appium plugin CLI 命令。本节仅仅是对服务提供商如何设计其面向用户的功能 API 的建议，这种设计原则上支持 Appium 本身在最终用户在自己的机器上运行 Appium 时将提供的所有功能。