コンテンツにスキップ

Appium 2 への移行

このドキュメントは、Appium 1 を使用していて Appium 2 に移行したいユーザー向けのガイドです。Appium 2 との互換性を確保するために、破壊的な変更点と環境またはテストスイートを移行する方法の一覧が含まれています。

Appium 2 の概要

Appium 2 は、5 年以上ぶりの Appium の最も大きな新しいリリースです。Appium 2 の変更は、主に特定のプラットフォームの自動化動作の変更に関連するものではありません。代わりに、Appium 2 は、与えられたプラットフォームの自動化サポートを導入するコードプロジェクトである「ドライバ」と、Appium の動作をオーバーライド、変更、拡張、または追加できるコードプロジェクトである「プラグイン」を簡単に作成および共有できるプラットフォームとして Appium を再考します。

同時に、Appium プロジェクトは、多くの古い非推奨の機能を削除する機会を捉えています。

これらを合わせると、Appium のインストール方法、ドライバとさまざまな機能の管理方法、およびプロトコルサポートにいくつかの破壊的な変更が導入されます。これらについては、以下で詳しく説明します。

破壊的な変更

‼ デフォルトサーバーベースパス

Appium 1 では、サーバーはデフォルトで https://#: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 と 2 つのドライバが一度にインストールされます。インストールまたは起動エラーが発生した場合は、既存の 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 パラメータであり、たとえば UiAutomator2 ドライバで使用する特定の Chromedriver バージョンの場所を設定するために使用できました。

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 Not Yet Implemented エラーが発生していました。現在では、コマンドを認識しないドライバーがアクティブでない場合、メインの Appium サーバーはコマンドに対応するルートを定義しないため、404 Not Found エラーが発生します。

‼ ドライバーのアップデート

以前は、iOS または Android ドライバーのアップデートを入手するには、これらのアップデートが Appium の新しいリリースに組み込まれるのを待ってから、Appium のバージョンをアップデートする必要がありました。Appium 2 では、Appium サーバーと Appium ドライバーは個別にバージョン管理され、リリースされます。つまり、ドライバーは独自のリリースサイクルを持つことができ、Appium サーバーの新しいリリースを待つことなく、最新のドライバーバージョンをすぐに取得できます。ドライバーのアップデートを確認する方法は、CLI を使用することです。

appium driver list --updates

アップデートがある場合は、任意のドライバーに対して update コマンドを実行できます。

appium driver update xcuitest

（update コマンドの詳細については、Extension CLI のドキュメントを参照してください）

Appium サーバー自体を更新するには、以前と同じように npm install -g appium を実行します。Appium サーバーの新しいバージョンをインストールしてもドライバーはそのまま残るため、全体のプロセスがはるかに高速になります。

最新ではなく特定のドライバーバージョンに更新する場合は、ドライバーをアンインストールし、update の代わりに install サブコマンドを使用して目的のバージョンをインストールしてください。

appium driver uninstall xcuitest
appium driver install [email protected]

‼ プロトコルの変更

Appium の API は W3C WebDriver プロトコルに基づいており、長年にわたってこのプロトコルをサポートしてきました。W3C WebDriver プロトコルがウェブ標準として設計される前は、Selenium と Appium の両方でいくつかの他のプロトコルが使用されていました。これらのプロトコルは「JSONWP」（JSON Wire Protocol）と「MJSONWP」（Mobile JSON Wire Protocol）でした。W3C プロトコルは、（M）JSONWP プロトコルとはいくつかの点でわずかに異なります。

Appium 2 までは、Appium は両方のプロトコルをサポートしており、古い Selenium/Appium クライアントでも新しい Appium サーバーと通信できました。Appium 2 では、古いプロトコルのサポートが削除され、現在は W3C WebDriver プロトコルとのみ互換性があります。

‼ ケイパビリティにはベンダープレフィックスを使用する必要がある

古いプロトコルと新しいプロトコルの大きな違いの1つは、ケイパビリティの形式にあります。以前は「desired capabilities」と呼ばれていましたが、現在は単に「capabilities」と呼ばれています。非標準のケイパビリティには、「ベンダープレフィックス」が必須になりました。標準のケイパビリティのリストは、WebDriver プロトコル仕様に記載されており、browserName や platformName など、いくつかの一般的なケイパビリティが含まれています。

これらの標準ケイパビリティは、引き続きそのまま使用されます。他のすべてのケイパビリティには、名前に「ベンダープレフィックス」を含める必要があります。ベンダープレフィックスとは、appium: のように、コロンで終わる文字列です。Appium のケイパビリティのほとんどは、標準の W3C ケイパビリティを超えているため、ベンダープレフィックスを含める必要があります（ドキュメントで特に指示がない限り、appium: を使用することをお勧めします）。例：

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

この要件は、Appium 2 をターゲットとするテストスイートにとって破壊的変更となる場合とそうでない場合があります。更新された Appium クライアント（少なくとも Appium チームが管理しているクライアント）を使用している場合、クライアントは必要なすべてのケイパビリティに対して appium: プレフィックスを自動的に追加します。新しいバージョンの Appium Inspector もこれを行います。クラウドベースの Appium プロバイダーもこれを行う場合があります。したがって、ケイパビリティにベンダープレフィックスがないというメッセージが表示された場合は、この方法で問題を解決できることを知っておいてください。

皆さんの作業を少しでも楽にするために、Appium 関連のすべてのケイパビリティを 1 つのオブジェクトケイパビリティである appium:options にグループ化するオプションも導入しました。通常は appium: プレフィックスを付けるものをすべて、この 1 つのケイパビリティにまとめてバンドルできます。以下は、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 Protocol の一部であり、W3C プロトコルの一部ではないコマンドは、利用できなくなりました。

  • TODO（これらのコマンドは特定され、削除されており、完了したらここで更新されます）

最新の Appium または Selenium クライアントを使用している場合、これらのコマンドにはアクセスできなくなっているはずなので、破壊的変更はまず第一にクライアント側に表示されるはずです。

‼ イメージ分析機能がプラグインに移動

Appium 2 の設計目標の 1 つは、コアではない機能を プラグインと呼ばれる特別な拡張機能に移行することです。これにより、ダウンロードに時間がかかったり、システム設定が追加で必要な機能をユーザーが選択できるようになります。Appium のさまざまな画像関連機能（画像の比較、画像による要素の検索など）は、images という公式にサポートされているプラグインに移動されました。

これらの画像関連メソッドを使用している場合は、引き続きアクセスするために次の 2 つの操作を行う必要があります。

  1. プラグインをインストールする：appium plugin install images
  2. コマンドラインで指定されたプラグインのリストに含めることで、Appium サーバーがプラグインを実行できる状態で開始するようにします。例：appium --use-plugins=images

画像関連のコマンドはクライアント側でも削除されるため、これらの機能にアクセスするには、クライアント側プラグインをインストールするためのプラグイン README の指示に従う必要があります。

‼ Execute Driver Script コマンドがプラグインに移動

高度な Execute Driver Script 機能（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 プロパティの値にカットアンドペーストするだけです。以前に --allow-insecure および --deny-insecure に指定していた CSV のようなファイルは、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のExtension CLIを介して、npm、git、GitHub、またはローカルファイルシステムからダウンロードまたはインストールできます。ドライバーの構築に興味がありますか？ ドライバーの構築ガイドをご確認ください。

🎉 設定ファイル

Appiumは、コマンドライン引数に加えて、設定ファイルをサポートするようになりました。簡単に言えば、Appium 1でCLIで指定する必要があったほとんどすべての引数を、設定ファイルで表現できるようになりました。設定ファイルは、JSON、JS、またはYAML形式にできます。詳細については、設定ガイドを参照してください。

クラウドプロバイダー向けの特別な注意事項

このドキュメントの残りの部分は、Appium全般に適用されていますが、Appium 2のアーキテクチャの変更の一部は、クラウドベースのAppiumホストであろうと内部サービスであろうと、Appium関連のサービスプロバイダーにとって破壊的な変更となります。結局のところ、Appiumサーバーのメンテナーは、エンドユーザーが使用したい可能性のあるさまざまなAppiumドライバーとプラグインをインストールして利用可能にする責任があります。

クラウドプロバイダーには、業界互換性のある方法でユーザーニーズをサポートするために、クラウドプロバイダー機能に関する推奨事項をよく読んで理解することをお勧めします。