跳至內容

移轉至 Appium 2

這份文件是為使用 Appium 1 並希望移轉到 Appium 2 的人所撰寫的指南。其中包含中斷變更清單，以及如何移轉您的環境或測試套件以確保與 Appium 2 相容。

Appium 2 概觀

Appium 2 是 Appium 在 5 年來最大的新版本。Appium 2 的變更並非主要與特定平台的自動化行為變更相關。相反地，Appium 2 將 Appium 重新構想為一個平台，其中「驅動程式」（引入特定平台自動化支援的程式碼專案）和「外掛程式」（允許覆寫、變更、擴充或新增 Appium 行為的程式碼專案）可以輕鬆建立和分享。

同時，Appium 專案也把握機會移除許多舊的和已棄用的功能。

這些變更總共對 Appium 的安裝方式、驅動程式和各種功能的管理方式，以及通訊協定支援帶來一些中斷變更。以下會詳細說明這些變更。

中斷變更

‼ 預設伺服器基本路徑

使用 Appium 1 時，伺服器會預設在 http://localhost:4723/wd/hub 上接受指令。/wd/hub 基本路徑是從 Selenium 1 遷移到 Selenium 2 時沿用下來的舊慣例，現在已不再適用。因此，伺服器的預設基本路徑現在為 /。如果您想保留舊行為，您可以透過命令列參數設定基本路徑，如下所示

appium --base-path=/wd/hub

您也可以將伺服器參數設定為 設定檔 屬性。

‼ 安裝驅動程式時設定

您安裝 Appium 1 時，所有可用的驅動程式會與 Appium 主伺服器同時安裝。現在不再是這樣。只安裝 Appium 2（例如，透過 npm i -g appium），只會安裝 Appium 伺服器，但不會安裝任何驅動程式。若要安裝驅動程式，您必須改用新的 Appium 擴充功能 CLI。例如，若要在安裝 Appium 後安裝最新版本的 XCUITest 和 UiAutomator2 驅動程式，您會執行下列指令

appium driver install uiautomator2     # installs the latest driver version
appium driver install [email protected]  # installs a specific driver version

至此，您的驅動程式已安裝完畢並準備就緒。您可以使用 Appium 2 命令列執行更多操作，因此務必查看 其文件。如果您在 CI 環境中執行，或想在一個步驟中安裝 Appium 和一些驅動程式，您可以使用安裝期間的一些特殊旗標執行，例如

npm i -g appium --drivers=xcuitest,uiautomator2

這將一次為您安裝 Appium 和兩個驅動程式。如果您遇到安裝或啟動錯誤，請移除任何現有的 Appium 1 npm 套件（使用 npm uninstall -g appium）。

‼ 驅動程式安裝路徑

您安裝 Appium 1 時，所有可用的驅動程式會與 Appium 主伺服器同時安裝在 /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-webdriveragent 現在會位於 $APPIUM_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent。

‼ Chromedriver 安裝標記

在 Appium 1 中，可以使用下列命令列標記，自訂 Chromedriver 的安裝方式（例如，作為 UiAutomator2 驅動程式的一部分）

  • --chromedriver-skip-install
  • --chromedriver-version
  • --chromedriver-cdnurl

由於 Appium 2 現在會為您安裝驅動程式，而且這些標記實作為 npm 設定檔標記，因此它們將不再運作。請改為在驅動程式安裝期間使用下列環境變數

  • APPIUM_SKIP_CHROMEDRIVER_INSTALL
  • CHROMEDRIVER_VERSION
  • CHROMEDRIVER_CDNURL

例如

APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2

‼ 驅動程式特定的命令列選項

在 Appium 1 中，特定於特定驅動程式的命令列選項都主機在 Appium 主伺服器上。因此，例如，--chromedriver-executable 是您可以與 Appium 搭配使用的 CLI 參數，用於設定特定 Chromedriver 版本的位置，以與 UiAutomator2 驅動程式搭配使用。

在 Appium 2 中，所有驅動程式和平台特定的 CLI 參數都已移至驅動程式本身。若要存取對應的功能，您需要參閱驅動程式/外掛程式文件。在某些情況下，擴充功能將繼續公開 CLI 參數。例如，XCUITest 驅動程式用於公開參數 --webdriveragent-port。現在，若要存取此參數，應加上 driver-xcuitest 前綴，以區別於其他驅動程式可能也公開的參數。因此，若要使用此參數，您需要使用類似下列內容啟動 Appium

appium --driver-xcuitest-webdriveragent-port=5000

有些驅動程式已完全取消 CLI 參數，而採用預設功能。例如，針對上述的 --chromedriver-executable 參數，您現在需要利用 UiAutomator2 驅動程式支援的 appium:chromedriverExecutable 功能。若要從命令列設定此功能，請執行下列動作

appium --default-capabilities '{"appium:chromedriverExecutable": "/path/to/chromedriver"}'

‼ 驅動程式特定的自動化指令

某些指令的定義僅與特定驅動程式相關，已移至這些驅動程式的實作。例如，pressKeyCode 是 UiAutomator2 驅動程式所特有，現在僅由該驅動程式理解。實際上，這裡唯一會中斷變更的是，如果您未安裝適當的驅動程式，您會遇到的錯誤類型。以前，如果您使用未實作指令的驅動程式，您會收到 501 尚未實作 錯誤。現在，您會收到 404 找不到 錯誤，因為如果不知道指令的驅動程式未啟用，主要的 Appium 伺服器將不會定義與指令相應的路由。

‼ 驅動程式更新

過去，要取得 iOS 或 Android 驅動程式的更新，您只需等待這些更新納入 Appium 的新版本，然後更新您的 Appium 版本。使用 Appium 2，Appium 伺服器和 Appium 驅動程式會個別進行版本控制和發布。這表示驅動程式可以按照自己的發布節奏進行，而且您可以立即取得最新的驅動程式版本，而不用等到新的 Appium 伺服器版本發布。檢查驅動程式更新的方式是使用 CLI

appium driver list --updates

如果有任何更新可用，您接著可以為任何特定驅動程式執行 update 指令

appium driver update xcuitest

(有關更新指令的完整說明，請查看 延伸模組 CLI 文件)

要更新 Appium 伺服器本身，您執行的動作與過去相同：npm install -g appium。現在，安裝 Appium 伺服器的版本不會影響您的驅動程式，因此整個程序會快很多。

如果您想要更新到特定驅動程式版本（而非最新版本），請解除安裝驅動程式，然後使用 install 子指令（而非 update）安裝所需的版本。

appium driver uninstall xcuitest
appium driver install [email protected]

‼ 通訊協定變更

Appium 的 API 是根據 W3C WebDriver 通訊協定，並且已支援此通訊協定多年。在 W3C WebDriver 通訊協定設計為網路標準之前，Selenium 和 Appium 都使用其他多種通訊協定。這些通訊協定是「JSONWP」（JSON Wire 通訊協定）和「MJSONWP」（行動裝置 JSON Wire 通訊協定）。W3C 通訊協定與 (M)JSONWP 通訊協定在一些小地方有所不同。

在 Appium 2 之前，Appium 支援兩種通訊協定，因此較舊的 Selenium/Appium 客户端仍可與較新的 Appium 伺服器進行通訊。Appium 2 已移除對較舊通訊協定的支援，現在僅相容於 W3C WebDriver 通訊協定。

‼ 功能必須使用供應商前綴

新舊通訊協定之間的一個顯著差異在於功能的格式。先前稱為「所需功能」，現在簡稱為「功能」，現在要求任何非標準功能都必須使用所謂的「供應商前綴」。標準功能清單載明於 WebDriver 通訊協定規格 中，並包含一些常用的功能，例如 browserName 和 platformName。

這些標準功能會繼續原樣使用。所有其他功能都必須在其名稱中包含「供應商前綴」。供應商前綴是一個字串，後接一個冒號，例如 appium:。Appium 的大多數功能都超越了標準 W3C 功能，因此必須包含供應商前綴（我們建議您使用 appium:，除非文件另有指示）。例如

  • appium:app
  • appium:noReset
  • appium:deviceName

當目標為 Appium 2 時，此要求可能會或可能不會對您的測試套件造成重大變更。如果您使用的是已更新的 Appium 客户端（至少是由 Appium 團隊維護的一個），則該客户端會自動為所有必要的功能加上 appium: 前綴。新版本的 Appium Inspector 也會執行此動作。基於雲端的 Appium 提供者也可能會執行此動作。因此，請注意，如果您收到任何訊息指出您的功能缺少供應商前綴，這就是解決此問題的方法。

為了讓每個人的生活更輕鬆，我們還引入了將所有與 Appium 相關的功能分組到一個物件功能 appium:options 的選項。您可以將任何通常會加上 appium: 前綴的項目組合到此功能中。以下是使用 appium:options 在 Safari 瀏覽器上啟動 iOS 會話的範例（以原始 JSON 格式呈現）

{
  "platformName": "iOS",
  "browserName": "Safari",
  "appium:options": {
    "platformVersion": "14.4",
    "deviceName": "iPhone 11",
    "automationName": "XCUITest"
  }
}

（當然，每個客户端都會有不同的方式來建立結構化功能，例如 appium:options 或您可能看過的其他功能，例如 goog:chromeOptions）。

注意

包含在 appium:options 物件中的功能會覆寫此物件外部使用的同名功能。（雲端提供者對 appium:options 語法的支援可能有所不同。）

如需有關功能的更多資訊，請參閱 功能指南。

‼ 已移除的指令

除了已移至驅動程式實作的指令外，舊 JSON Wire 協定中且非 W3C 協定一部分的指令已不再可用

  • 待辦事項（這些指令正進行識別和移除，完成後將在此處更新）

如果您使用的是現代 Appium 或 Selenium 應用程式，您不應再存取這些指令，因此任何重大變更應首先且最重要的是出現在應用程式端。

‼ 影像分析功能已移至外掛程式

Appium 2 的設計目標之一是將非核心功能移轉至稱為 外掛程式 的特殊擴充功能。這允許人們選擇需要額外時間下載或額外系統設定的功能。Appium 的各種與影像相關的功能（影像比對、透過影像尋找元素等）已移至名為 images 的官方支援外掛程式。

如果您使用這些與影像相關的方法，若要繼續存取它們，您需要執行兩件事

  1. 安裝外掛程式：appium plugin install images
  2. 確保您在命令列中包含指定外掛程式的清單，以存取執行外掛程式的權限來啟動 Appium 伺服器，例如，appium --use-plugins=images

與影像相關的指令也將從應用程式端移除，這表示您需要遵循外掛程式 README 中的說明，安裝應用程式端外掛程式才能存取這些功能。

‼ 執行驅動程式指令已移至外掛程式

如果您使用進階執行驅動程式指令功能（允許您傳送 WebdriverIO 指令，讓它在伺服器上完全執行，而非從應用程式端逐一執行指令），此功能已移至外掛程式。以下是如何繼續使用它的方法

  1. 安裝外掛程式：appium plugin install execute-driver
  2. 確保您在命令列中包含指定外掛程式的清單，以存取執行外掛程式的權限來啟動 Appium 伺服器，例如，appium --use-plugins=execute-driver

‼ --nodeconfig、--default-capabilities、--allow-insecure 和 --deny-insecure 不再支援外部檔案

這些選項可以在命令列中提供為字串（--nodeconfig 的 JSON 字串，以及 --allow-insecure 和 --deny-insecure 的逗號分隔字串清單）。在命令列中提供的引數可能需要加上引號或跳脫字元。

提供這些選項的建議方法是透過 設定檔。

總之，如果你使用 JSON Appium 設定檔，你可以簡單地將「nodeconfig」JSON 檔的內容剪下並貼到 server.nodeconfig 屬性的值中。你先前提供的任何類似 CSV 的檔，例如 --allow-insecure 和 --deny-insecure，會變成 Appium 設定檔中 server.allow-insecure 和 server.deny-insecure 屬性的值（分別為字串陣列）；兩者都是字串陣列。

‼ 移除舊驅動程式

舊的 iOS 和 Android（UiAutomator 1）驅動程式和相關工具（例如 authorize-ios）已被移除。它們已經很多年沒有相關性了。

‼ 伺服器無法再使用 --port 0 啟動

在 Appium 1 中，可以在伺服器啟動期間指定 --port 0。這會讓 Appium 在隨機的可用埠上啟動。在 Appium 2 中，埠值必須是 1 或更高。隨機埠指派從來都不是 Appium 1 的預期功能，而是 Node 的 HTTP 伺服器運作方式和 Appium 1 中沒有埠輸入驗證所造成的結果。如果你想找到隨機的可用埠來啟動 Appium，現在必須在啟動 Appium 之前自行處理。在明確且已知的埠上啟動 Appium 是未來的正確做法。

⚠ 內部套件已重新命名

一些 Appium 內部的 NPM 套件已重新命名（例如，appium-base-driver 現在是 @appium/base-driver）。這對 Appium 使用者來說不是重大變更，只有對直接整合 Appium 程式碼來建置軟體的人來說是重大變更。

⚠ wd JavaScript 用戶端程式庫不再支援

多年來，Appium 的一些作者維護 WD 用戶端程式庫。此程式庫已棄用，且未更新為與 W3C WebDriver 協定搭配使用。因此，如果你使用此程式庫，你需要轉移到較新的程式庫。我們建議使用 WebdriverIO。

⚠ Appium Desktop 已被 Appium Inspector 取代

Appium Desktop 的檢查功能已移至其專屬應用程式：Appium Inspector。它與獨立的 Appium 2 伺服器完全相容，但也能與後續版本的 Appium 1 伺服器搭配使用。Appium Desktop 本身已不再使用，且與 Appium 2 不相容。

除了應用程式之外，Appium Inspector 還提供瀏覽器版本，可於 inspector.appiumpro.com 存取。請注意，若要將瀏覽器版本與本機 Appium 伺服器搭配使用，您需要先使用 --allow-cors 旗標啟動伺服器。

主要新功能

除了上述重大變更之外，本節列出您可能希望在 Appium 2 中利用的一些主要新功能。

外掛程式

🎉 伺服器外掛程式

Appium 擴充功能作者現在可以開發自己的伺服器外掛程式，這些外掛程式可以攔截和修改任何 Appium 指令，甚至可以調整底層 Appium HTTP 伺服器本身的運作方式。若要深入了解外掛程式，請參閱新的 Appium 簡介。有興趣建立外掛程式嗎？請查看 建立外掛程式 指南。

🎉 從任何地方安裝驅動程式和外掛程式

您不再受限於 Appium 附帶的驅動程式，或 Appium 團隊所知的驅動程式！Appium 擴充功能作者現在可以開發自訂驅動程式，這些驅動程式可以透過 Appium 的 擴充功能 CLI 從 npm、git、GitHub，甚至本機檔案系統下載或安裝。有興趣建立驅動程式嗎？請查看 建立驅動程式 指南。

🎉 組態檔

除了命令列參數之外，Appium 現在還支援組態檔。簡而言之，Appium 1 要求在 CLI 上提供的幾乎所有參數現在都可以透過組態檔來表達。組態檔可以是 JSON、JS 或 YAML 格式。請參閱 組態指南 以取得完整說明。

雲端供應商的特別注意事項

本文檔的其餘部分通常適用於 Appium，但 Appium 2 中的某些架構變更將構成 Appium 相關服務提供者的重大變更，無論是基於雲端的 Appium 主機或內部服務。最終，Appium 伺服器的維護者負責安裝和提供最終使用者可能想要使用的各種 Appium 驅動程式和外掛程式。

我們鼓勵雲端供應商徹底閱讀和了解我們的 雲端供應商功能建議，以便以符合產業標準的方式支援使用者需求！