セッション機能

「機能」とは、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ドライバーに、セッションの開始時とクリーンアップ時に通常の réinitialiser logique を回避するように指示します（デフォルトは`false`）。
`appium:fullReset`	`ブール値`	いいえ	trueの場合、Appiumドライバーに、通常の réinitialiser logique に追加の手順を追加して、環境の再現性を最大限に確保するように指示します（デフォルトは`false`）。
`appium:eventTimings`	`ブール値`	いいえ	trueの場合、Appiumドライバーにイベントタイミングを収集するように指示します（デフォルトは`false`）。
`appium:printPageSourceOnFindFailure`	`ブール値`	いいえ	trueの場合、要素の検索リクエストが失敗するたびに、ページソースを収集してAppiumログに出力します（デフォルトは`false`）。

一部のドライバーは、機能グループに対してより複雑な制約を課します。たとえば、appium:app機能とbrowserName機能は上記ではオプションとしてリストされていますが、特定のアプリでセッションを開始する場合、XCUITestドライバーでは、appium:app、browserName、またはappium:bundleIdの少なくとも1つが機能に含まれている必要があります（そうでない場合、インストールおよび/または起動するアプリがわからず、ホーム画面でセッションを開くだけです）。各ドライバーは、これらの機能の解釈方法とその他のプラットフォーム固有の要件を文書化します。

注記

機能は、セッションを開始するときに使用されるパラメータのようなものです。機能が送信され、セッションが開始された後、それらを変更することはできません。ドライバーがセッション中に動作の側面を更新することをサポートしている場合、機能の代わりに、または機能に加えて、設定を提供します。

各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
    }
}

オブジェクトである機能値を構築することは言語によって異なります。これを実現する方法の ulteriori 例については、クライアントのドキュメントを参照してください。

警告

appium:optionsの内側と外側の両方に同じ機能を含めると、appium:optionsの内側の値が優先されます。

Always-Match機能とFirst-Match機能¶

W3C仕様により、クライアントは、新しいセッションリクエストに応じて作成されるセッションの種類にAppiumサーバーにある程度の柔軟性を与えることができます。これは、「always-match」機能と「first-match」機能の概念によるものです。

Always-match機能は、単一の機能セットで構成され、新しいセッションリクエストを続行するには、サーバーがすべてのメンバーを満たしている必要があります。
First-match機能は、機能セットの配列で構成されます。各セットはalways-match機能とマージされ、サーバーが処理方法を知っている最初のセットが、セッションの開始に使用されるセットになります。

注記

機能の処理方法の詳細については、仕様自体または要約版をご覧ください。

実際には、Appiumでfirst-match機能を使用する必要はありません。代わりに、Appiumサーバーに処理させたい明示的な機能セットを定義することをお勧めします。これらはalways-match機能としてエンコードされ、first-match機能の配列は空になります。

とはいえ、AppiumはW3C仕様で定義されているalways-match機能とfirst-match機能を*理解し*ているため、これらの機能を使用すると、Appiumは期待どおりに機能します。 always-match機能とfirst-match機能を定義するプロセスは、各クライアントライブラリに固有であるため、クライアントライブラリのドキュメントを参照して、その仕組みの例を確認してください。

クラウドプロバイダー向けの特記事項¶

警告

このセクションは、Appiumのエンドユーザー向けではなく、Appium互換のクラウドサービスを構築する開発者向けです。

Appiumクラウドを管理する場合、ユーザーはAppiumドライバーとプラグインのさまざまな独立したバージョンをターゲットにすることができます。公式またはサードパーティのドライバーまたはプラグインの検出、インストール、および可用性を実装する方法は、もちろん各サービスプロバイダー次第です。しかし、Appiumチームは、業界全体の一貫性のために、いくつかの提案を提供しています。 *これらは推奨事項に過ぎず*、標準ではありませんが、クラウド環境でのAppium2の作業に伴う複雑さの増加をユーザーが理解するのに役立ちます。

推奨される機能¶

標準の 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"}`
`プラグイン`	アクティブ化する必要があるプラグインのリスト（および場合によってはプラグインのバージョン）（詳細は以下を参照）。	`["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"]
  }
}

この機能セットは、バージョン 3.52.0 の XCUITest ドライバーと、アクティブな images プラグインをサポートする Appium 2+ サーバーを要求します。このセットは、クラウドプロバイダーが簡単に検証できます。クラウドプロバイダーは、これらの機能に応じて、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 コマンドを実行したりするのは、サービスプロバイダー次第です。このセクションは、サービスプロバイダーが、Appium 自体がエンドユーザーに Appium を独自に実行している場合に提供するすべての機能を原則としてサポートする方法で、ユーザー向けの機能 API を設計する方法についての単なる提案です。