コンテンツにスキップ

Appium 1.xからAppium 2.xへ移行する

このドキュメントは既にAppium 1.xを利用している人がAppium 2.xに移行するための手引きです。 破壊的変更(breaking changes)の一覧や、実行環境・テストコードをAppium 2.0互換にするための方法が含まれます。

Note

Appiumは継続的に開発されているため、このドキュメントはAppiumドライバーやプラグインに関して情報古い可能性があります。

Appium 2.0の概要

Appium 2.0は過去5年間におけるAppiumのリリース野中で最も大きなリリースです。Appium 2.0の主要な変更は特定のプラットフォームに対する自動化された動作に関するものではありません。Appium 2.0はAppiumをドライバー(drivers)(あるプラットフォームに対する自動化を支援するためのプロジェクト)とプラグイン(plugins)(Appiumの動作を上書き、代替、拡張、もしくは追加するためのプロジェクト)という容易に実装、共有できる仕組みを提供するプラットフォームとして再考しています。

同時に、Appiumプロジェクトは多くの古くなったり非推奨となっている機能や依存を取り除こうとしています。

これらに合わせて、Appiumのインストール方法、ドライバーやフィーチャーの管理、プロトコルサポートに関していくつかの破壊的変更をが導入されます。詳細は以下になります。

破壊的変更

以下では破壊的変更と、何をする必要があるのかを示します。

‼ 初期設定のbase path

Appium 1.xでは、AppiumサーバーのURLはhttp://localhost:4723/wd/hubでした。この/wd/hubであるbase pathはSelenium 1からSelenium 2へ移行した時の名残であり、今となっては何ら意味を持ちません。そのため、初期設定のbase pathは/となります。もしあたなが以前の挙動を保持したいのであれば、以下の通りにAppiumサーバを起動してください。

appium --base-path=/wd/hub

この設定はConfig fileからでも可能です。

‼ ドライバーのインストール

Appium 1.xをインストールしたとき、全ての入手可能なドライバーはAppiumサーバーと合わせてインストールされていました。しかしAppium 2.0では異なります。Appium 2.0のインストール(例えば npm i -g appium を実行した時)は単にAppiumサーバーのみをインストールし、ドライバーはインストールされません。ドライバーをインストールするためには新しいAppium拡張コマンドラインインタフェース(Appium extension CLI)を使わなければいけません。例えば、最新のXCUITestとUiAutomator2ドライバーをインストールする場合、Appiumをインストールしたのちに次のコマンドを実行する必要があります。

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

これにより、ドライバーがインストールされ、利用可能になります。このCLIはいろいろな機能を提供しているので、CLIのドキュメントを確認してみてください。もしCI上で実行したり、いくつかのドライバーをAppiumと一緒にインストールしたい場合、以下のようなフラグを利用することが可能です。

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

これはAppiumと2つのドライバーを、1つのコマンドでインストールします。もしセットアップで何らかの問題が発生した場合、既存のAppium 1.xをnpm uninstall -g appiumで削除してみてください。

‼ ドライバーがインストールされるパス

Appium 1.xをインストールしたとき、全ての入手可能なドライバーは主要なAppiumサーバーと合わせてインストールされていました。 そのパスは/path/to/appium/node_modulesです。 例えば、手動でWebDriverAgentをビルドするためのappium-webdriveragentパッケージは、/path/to/appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragentでした。

Appium 2.0では、このような依存関係を環境変数 APPIUM_HOME にインストールします。デフォルトのパスは ~/.appium です。 そのため、XCUITestドライバーパッケージをインストールすると、appium-webdriveragent へのパスは $APPIUM_HOME/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent となります。

‼ Chromeドライバーのインストールフラグ

Appium 1.xでは、以下のコマンドラインフラグを使って、(例えばUiAutomator2ドライバーの一部として)Chromedriverをインストールする方法の変更が可能でした。

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

Appium 2.0では必要なドライバーだけインストールするようになり、またこれらのフラグはnpmの設定フラグとして実装されたため、これらのコマンドラインフラグは機能しません。代わりに、ドライバーのインストール時に以下の環境変数を使用してください：

  • APPIUM_SKIP_CHROMEDRIVER_INSTALL
  • CHROMEDRIVER_VERSION
  • CHROMEDRIVER_CDNURL

例：

APPIUM_SKIP_CHROMEDRIVER_INSTALL=1 appium driver install uiautomator2

‼ ドライバー特有のコマンドラインオプション

Appium 1.xでは、特定のドライバに特化したコマンドラインオプションは、すべてAppiumサーバーに中継されていました。 そのため、例えば--chromedriver-executableは、UiAutomator2ドライバーで使用する特定のChromedriverバージョンの場所を設定するためにAppiumで使用できるCLIパラメータでした。

Appium 2.xでは、すべてのドライバーとプラットフォーム固有の CLI パラメータは、それらのドライバー自体が管理するかたちに移行しました。これらにアクセスするには、引数の前に拡張機能の種類 (driver または plugin) と拡張機能の名前を付ける必要があります。例えば、--chromedriver-executable は --driver-uiautomator2-chromedriver-executable となります。

‼ ドライバー特有の自動化コマンド

特定のドライバーにのみ関係するコマンドの定義は、そのドライバーの実装に移行しました。 例えば、pressKeyCodeはUiAutomator2ドライバー特有のものなので、現在ではそのドライバーのみが解釈できます。 実際には、適切なドライバーがインストールされていない場合に発生するエラーの種類が変わります。 以前は、ドライバーが未実装のコマンドを実行すると 501 Not Yet Implemented というエラーが返却されていました。 現在では、コマンドを実装していないドライバーがアクティブでない場合、主Appiumサーバーはそのコマンドは定義されていないと処理し、404 Not Found エラーを返却します。

‼ Driver updates

以前は、iOSやAndroidに関わるドライバーの更新を入手するために、Appiumの新しいリリースにそれらの更新が組み込まれるのを待ち、Appiumのバージョンを更新していました。 Appium 2.xでは、AppiumサーバーとAppiumドライバーは各々にバージョンが管理され、別々にリリースされます。 つまりドライバーは独自のリリース周期で、新しいAppiumサーバーのリリースを待つのではなく、その都度更新を適用することができます。

ドライバーの更新をCLIでチェックする方法:

appium driver list --updates

更新が入手可能であれば、任意のドライバーに対して update コマンドを実行することができます。

appium driver update xcuitest

(更新コマンドの詳しい説明は Extension CLI を確認してください。)

Appium サーバー自体を更新するには、これまでと同じように npm i -g appium を実行します。現在、Appiumサーバーの新しいバージョンをインストールしても、ドライバーはそのままなので、プロセス全体がより迅速になります。

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

appium driver uninstall xcuitest
appium driver install [email protected]

‼ プロトコルの変更

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

Appium 2.0までは、古いSelenium/Appiumクライアントが新しいAppiumサーバーと通信できるように、Appiumは両方のプロトコルをサポートしていました。今後、古いプロトコルのサポートは削除されます。

‼ Capabilitiesはベンダープレフィックスを使用しなければならない

古いプロトコルと新しいプロトコルの大きな違いのひとつは、Capabilitiesのフォーマットにあります。以前は "desired capabilities" と呼ばれていましたが、現在は単に "capabilities" と呼ばれ、非標準の機能にはいわゆる "vendor prefix" が要求されるようになりました。標準として組み込まれているcapabilitiesは WebDriver Protocol spec に記載されており、browserName や platformName などのよく使われるcapabilitiesが含まれています。

これらの標準として組み込まれているcapabilitiesはそのまま使用され続けます。それ以外のすべてのcapabilitiesは、その名前に"vendor prefix"を 含まなければなりません。"vendor prefix"は、appium: のように、コロンが続く文字列です。Appiumのほとんどのcapabilitiesは、標準として組み込まれているcapabilitiesではないため、"vendor prefix"を含める必要があります(ドキュメントで指示がない限り、appium: を使用することを推奨します)。 例えば、

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

この要件は、Appium 2.0をターゲットにしているテストスイートにとって破壊的な変更になるかもしれませんし、ならないかもしれません。 アップデートされたAppiumクライアント(少なくとも Appium チームによってメンテナンスされているもの)を使用している場合、クライアントは自動的にすべての必要なcapabilitiesに appium: 接頭辞を追加します。新しいバージョンのAppium Inspectorも同様です。クラウドベースのAppiumプロバイダもこれを行うかもしれません。 そのため、もしあなたが使っていcapabilitiesに vendor prefix がない旨のメッセージが表示された場合は、この方法で問題を解決することができます。

これに関連して、W3CプロトコルをサポートしていないWebDriverクライアントを使用してAppiumセッションを開始することはできなくなります(WDライブラリに関するこの趣旨のコメントは以下を参照してください)。

みなさんの活動を少し楽にするために、Appiumに関連する全てのcapabilitiesを一つのオブジェクトにまとめるオプション(appium:options)も導入しました。通常、appium:接頭辞を付けるものを、この1つのcapabilityにまとめることができます。以下は appium:options を使ってSafariブラウザ上でiOSセッションを開始する例(JSON)です：

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

(もちろん、appium:optionsのような構造化されたcapabilityや、goog:chromeOptionsのような構造化されたcapabilityは、クライアントによって作成方法が異なります。)

Note

appium:optionsで表示されるcapabilityは、オブジェクトのトップレベルで表示される同名のcapabilityを上書きします。 (新しい appium:options 構文のサポートは、クラウドプロバイダによって異なる場合があります。)

ケイパビリティの詳細については、Capabilities Guideをご覧ください。

‼ 削除されたコマンド

ドライバの実装に移行したコマンドに加え、旧JSON Wireプロトコルの一部であり、W3Cプロトコルの一部ではないコマンドは使用できなくなりました：

  • TODO(これらのコマンドは特定・削除中であり、完了次第ここに更新されます)

最新のAppiumやSeleniumクライアントを使用している場合、これらにアクセスすることはできないため、どのような破壊的変更もまずはクライアント側に現れるはずです。

‼ 画像解析機能をプラグインに移行

Appium 2.0の設計目標の1つは、非コア機能をpluginsと呼ばれる特別な拡張機能に移行することです。これにより、ダウンロード時間やシステム設定が追加で必要となる機能を選択して利用できるようになります。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の場合はカンマ区切りの文字列リスト)。コマンドラインで指定する引数は、引用符で囲むかエスケープする必要があります。

これらのオプションを提供するために推奨される方法は、Configuration Fileを使うことです。

つまり、JSON Appium configファイルを使用している場合、単純に "nodeconfig" JSON ファイルの内容を server.nodeconfig プロパティの値にカット＆ペーストすることができます。 以前 --allow-insecure と --deny-insecure のために提供した CSV のようなファイルは、Appium config ファイルの server.allow-insecure プロパティと server.deny-insecure プロパティの値になります(それぞれ文字列の配列)。

‼ 古いドライバーを削除

古いiOSとAndroid(UiAutomator 1)のドライバーと関連ツール(例えばauthorize-ios)は削除されました。いずれにせよ、これらは何年も関連していません。

‼ サーバは --port 0 で起動することはできない

Appium 1.xでは、サーバー起動時に--port 0を指定することができました。 これはランダムな空きポートで Appium を起動するという効果があります。Appium 2.0 では、ポートの値は 1 以上でなければなりません。 ランダムなポートのランダムな割り当ては、Appium 1.x の意図的な機能ではありませんでした。HTTP サーバーがどのように動作するか、そして Appium 1.xにはポート入力の検証がなかった結果です。 Appium を起動するためにランダムな空きポートを見つけたい場合は、Appium を起動する前に自分でこの処理を行う必要があります。 明示的な既知のポートでAppiumを起動するのが、今後の正しいやり方です。

⚠ 内部パッケージの名称変更

一部の Appium 内部のnpmパッケージの名前が変更されました（例えば、appium-base-driver は @appium/base-driver になりました）。これはAppiumのユーザーにとって大きな変更ではなく、Appiumのコードを直接組み込んだソフトウェアをビルドしている人にとっての変更です。

⚠ "WD "JavaScriptクライアント・ライブラリがサポート終了

何年もの間、Appiumの作者の一部はWDクライアントライブラリを保守していました。このライブラリは非推奨であり、W3C WebDriverプロトコルで使用するためには更新されていません。そのため、このライブラリを使用している場合は、より最新のものに移行する必要があります。WebdriverIOをお勧めします。

⚠ Appium InspectorがAppium Desktopから分離

Appium Desktopのインスペクション部分は、専用のアプリAppium Inspector github.com/appium/appium-inspector に移動しました。Appium 2.0サーバーと完全に互換性があります。ダウンロードして実行するだけです。アプリを検査するためにGUIのAppium Desktopサーバーはもう必要ありません。Appium Desktopサーバーは、github.com/appium/appium-desktopで引き続きサポートされます。単にInspectorがバンドルされなくなるだけです。Appium Desktop 1.21以下のバージョンは、非推奨のWDクライアントに依存しており、Appium 2.0と互換性がないことに注意してください。現在、Appium DesktopのAppium 2.0サポートは予定されていません。

また、Web 版 Appium Inspector にアクセスすることで、何もダウンロードせずに Appium Inspector を使用できるようになりました。なお、ローカルサーバーに対してテストを行う場合は、ブラウザベースのAppium InspectorがAppiumサーバーにアクセスしてセッションを開始できるように、サーバーを --allow-cors で起動する必要があります。

主な新機能

上記の変更点とは別に、このセクションではAppium 2.0の主な新機能を紹介します。

プラグイン

🎉 Server Plugins

Appium extensionの作者は、独自のサーバー・プラグインを開発できるようになりました。 Appium HTTPサーバー自体の動作方法を調整することもできます。 プラグインの詳細については、新しいAppium Introductionをお読みください。 プラグインを作ることに興味がありますか？ プラグインの構築 ガイドをチェックしてください。

🎉 どこからでもドライバーとプラグインをインストール

もはやAppium付属のドライバーや、Appiumチームが知っているドライバーに限定されることはありません！Appiumエクステンションの作者は、カスタムドライバを開発できるようになりました。 AppiumのExtension CLI経由で、npm、git、GitHub、またはローカルのファイルシステムからダウンロードまたはインストールできます。 ドライバのビルドに興味がありますか？ ドライバのビルド ガイドを参照してください。

🎉 Configuration Files

Appiumは、コマンドライン引数に加え、設定ファイル もサポートするようになりました。つまりAppium 1がCLIで提供することを要求していたほぼすべての引数が、設定ファイルを介して表現できるようになりました。設定ファイルは JSON, JS, YAML 形式があります。設定ファイルは Config Guide を参照してください。

クラウド・プロバイダーに関する特記事項

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

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