會話功能

「功能」是開始 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`	`布林值`	否	如果為 true，指示 Appium 驅動程式在會話開始和清理期間避免其通常的重設邏輯（預設為 `false`）
`appium:fullReset`	`布林值`	否	如果為 true，指示 Appium 驅動程式擴充其通常的重設邏輯，並採取其他步驟以確保最大的環境可重複性（預設為 `false`）
`appium:eventTimings`	`布林值`	否	如果為 true，指示 Appium 驅動程式收集事件時序（預設為 `false`）
`appium:printPageSourceOnFindFailure`	`布林值`	否	如果為 true，在尋找元素的請求失敗時收集頁面來源並將其列印到 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 團隊確實提供了一些建議，以確保整個產業的一致性。這些建議僅供參考， 並非標準，但採用這些建議將有助於使用者在雲端環境中使用 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`
`自動化版本`	應使用的驅動程式版本（由 `appium:automationName` 指定）。	`1.55.2`
`自動化`	要使用的自訂驅動程式的名稱（請參閱下方以取得更多資訊）。這將會覆寫 `appium:automationName` 和 `$cloud:automationVersion`。	`{"name": "@org/custom-driver", "source": "github", "package": "custom-driver"}`
`外掛程式`	應啟用的外掛程式清單（以及外掛程式的版本）。（請參閱下方以取得更多資訊）。	`["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"]
  }
}

這組功能要求 Appium 2+ 伺服器支援版本 3.52.0 的 XCUITest 驅動程式，並啟用 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 pluginCLI 命令。本節僅為建議，說明服務提供者如何設計其面向使用者的功能 API，原則上支援 Appium 本身會提供給最終使用者的所有功能，如果他們自行執行 Appium。