翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# IDT テストケース実行可能ファイルを作成する
テストケース実行可能ファイルは、次の方法でテストスイートフォルダ内に作成して配置できます。
+ `test.json` ファイル内の引数または環境変数を使用して実行するテストを決定するテストスイートの場合は、テストスイート全体に対して 1 つのテストケース実行可能ファイルを作成することも、テストスイート内のテストグループごとに 1 つのテスト実行可能ファイルを作成することもできます。
+ 指定したコマンドに基づいて特定のテストを実行するテストスイートの場合は、テストスイート内のテストケースごとに 1 つのテストケース実行可能ファイルを作成します。
テストを作成するユーザーは、ユースケースに適したアプローチを決定し、それに応じてテストケースの実行可能ファイルを設定できます。各 `test.json` ファイルに、正しいテストケース実行可能ファイルのパスを指定していること、および指定した実行可能ファイルが正常に実行されることを確認してください。
すべてのデバイスにテストケースを実行する準備が整うと、IDT は以下のファイルを読み取ります。
+ `test.json`。選択されたテストケースが、開始するプロセスと設定する環境変数を決定するために使用します。
+ `suite.json`。テストスイートが、設定する環境変数を決定するために使用します。
IDT は、`test.json` ファイルで指定されているコマンドと引数に基づいて、必要なテスト実行可能プロセスを開始し、必要な環境変数をプロセスに渡します。
## IDT クライアント SDK を使用する
IDT クライアント SDK を使用すると、IDT とテスト対象のデバイスとのやり取りに使用できる API コマンドを使用して、テスト実行可能ファイルにテストロジックを簡単に記述できます。現在、IDT では次の SDK が用意されています。
+ IDT クライアント SDK for Python
+ IDT クライアント SDK for Go
+ IDT Client SDK for Java
これらの SDK は、`/sdks` フォルダにあります。新しいテストケース実行可能ファイルを作成するときは、使用する SDK をテストケース実行可能ファイルが含まれるフォルダにコピーし、コード内で SDK を参照する必要があります。このセクションでは、テストケースの実行可能ファイルで使用できる API コマンドについて簡単に説明します。
**Topics**
+ [デバイスとのやり取り](#api-device-interaction)
+ [IDT とのやり取り](#api-idt-interaction)
+ [ホストとのやり取り](#api-host-interaction)
### デバイスとのやり取り
次のコマンドを使用すると、デバイスとのやり取りや接続管理のための追加の関数を実装せずに、テスト対象デバイスと通信することができます。
`ExecuteOnDevice`
テストスイートが、SSH または Docker シェル接続をサポートするデバイス上で、シェルコマンドを実行できるようにします。
`CopyToDevice`
テストスイートが、IDT を実行するホストマシンから、SSH または Docker シェル接続をサポートするデバイス上の指定された場所にローカルファイルをコピーできるようにします。
`ReadFromDevice`
テストスイートが、UART 接続をサポートするデバイスのシリアルポートから読み取りできるようにします。
**注記**
IDT は、コンテキストからのデバイスアクセス情報を使用して確立されたデバイスへの直接接続を管理しないため、テストケース実行可能ファイルでは、デバイスとやり取り用のこれらの API コマンドを使用することをお勧めします。ただし、これらのコマンドがテストケースの要件を満たしていない場合は、IDT コンテキストからデバイスアクセス情報を取得し、この情報を使用してテストスイートからデバイスに直接接続できます。
直接接続するには、テスト対象デバイスとリソースデバイスそれぞれの `device.connectivity` フィールドと `resource.devices.connectivity` フィールドの情報を取得します。IDT コンテキスト使用の詳細については、[IDT コンテキストを使用する](idt-context.md)を参照してください。
### IDT とのやり取り
次のコマンドを使用すると、テストスイートが IDT と通信できるようになります。
`PollForNotifications`
テストスイートが IDT からの通知をチェックできるようにします。
`GetContextValue ` および `GetContextString`
テストスイートが IDT コンテキストから値を取得できるようにします。詳細については、[IDT コンテキストを使用する](idt-context.md) を参照してください。
`SendResult`
テストスイートがテストケースの結果を IDT にレポートできるようにします。このコマンドは、テストスイートの各テストケースの最後に呼び出す必要があります。
### ホストとのやり取り
次のコマンドを使用すると、テストスイートがホストマシンと通信できるようになります。
`PollForNotifications`
テストスイートが IDT からの通知をチェックできるようにします。
`GetContextValue ` および `GetContextString`
テストスイートが IDT コンテキストから値を取得できるようにします。詳細については、[IDT コンテキストを使用する](idt-context.md) を参照してください。
`ExecuteOnHost`
テストスイートがローカルマシン上でコマンドを実行できるようにし、IDT がテストケース実行可能ファイルのライフサイクルを管理できるようにします。
## IDT CLI コマンドを有効にする
`run-suite` コマンド IDT CLI には、テストの実行者がテスト実行をカスタマイズするためのいくつかのオプションがあります。テストの実行者がこれらのオプションを使用してカスタムテストスイートを実行できるようにするには、IDT CLI のサポートを実装します。サポートを実装しなくてもテストは実行できますが、一部の CLI オプションは正しく機能しません。理想的なカスタマーエクスペリエンスを提供するために、IDT CLI で `run-suite` コマンドの次の引数のサポートを実装することをお勧めします。
`timeout-multiplier`
テストの実行中にすべてのタイムアウトに適用される 1.0 より大きい値を指定します。
テストの実行者は、この引数を使用して、実行するテストケースのタイムアウトを増やすことができます。テストの実行者が `run-suite` コマンドにこの引数を指定すると、IDT はこの値を使用して IDT\$1TEST\$1TIMEOUT 環境変数の値を計算し、IDT コンテキストの `config.timeoutMultiplier` フィールドを設定します。この引数をサポートするには、以下の手順を実行する必要があります。
+ `test.json` ファイルのタイムアウト値を直接使用する代わりに、IDT\$1TEST\$1TIMEOUT 環境変数を読み取り、正しく計算されたタイムアウト値を取得します。
+ IDT コンテキストから `config.timeoutMultiplier` 値を取得し、長時間実行されるタイムアウトに適用します。
タイムアウトイベントによる早期終了の詳細については、[終了動作を指定する](#test-exec-exiting)を参照してください。
`stop-on-first-failure`
障害が発生した場合に、IDT がすべてのテスト実行を停止するように指定します。
テストの実行者がこの引数を `run-suite` コマンドを指定すると、IDT は障害が発生するとすぐにテストの実行を停止します。ただし、テストケースが並行して実行されている場合、この設定によって予期しない結果につながる可能性があります。このサポートを実装するには、テストロジックを使用して、IDT がこのイベントに遭遇した場合に、実行中のすべてのテストケースに対して、実行を停止し、一時リソースをクリーンアップし、テスト結果を IDT にレポートするように指示します。障害発生時の早期終了の詳細については、[終了動作を指定する](#test-exec-exiting)を参照してください。
`group-id` および `test-id`
IDT が選択されたテストグループまたはテストケースのみを実行するように指定します。
テストの実行者は、`run-suite` コマンドでこれらの引数を使用して、以下のテスト実行可能ファイルの動作を指定できます。
+ 指定されたテストスイート内のすべてのテストグループを実行する。
+ 指定されたテストグループ内から選択したテストを実行する。
これらの引数をサポートするには、テストスイート用のステートオーケストレーターに、自分のテストオーケストレーターの `RunTask` ステートおよび `Choice` ステートのセットが含まれている必要があります。カスタムステートマシンを使用しない場合は、デフォルトの IDT テストオーケストレーターに必要なステートが含まれているため、追加のアクションを行う必要はありません。ただし、カスタムテストオーケストレーターを使用している場合は、サンプルとして [ステートマシンの例: ユーザーが選択したテストグループを実行する](idt-state-machine.md#allow-specific-groups) を使用して、自分のテストオーケストレーターに必要なステートを追加してください。
IDT CLI コマンドの詳細については、[カスタムテストスイートのデバッグと実行](run-debug-custom-tests.md)を参照してください。
## イベントログの書き込み
テストの実行中は、イベントログとエラーメッセージをコンソールに書き込むために `stdout` と `stderr` にデータを送信します。コンソールメッセージの形式の詳細については、[コンソールメッセージの形式](idt-review-results-logs.md#idt-console-format)を参照してください。
IDT がテストスイートの実行を終了すると、この情報は `/results//logs` フォルダにある `test_manager.log` ファイルでも利用可能になります。
各テストケースは、テスト実行のログ (テスト対象デバイスのログを含む) を `/results/execution-id/logs` フォルダにある `_` ファイルに書き込むように設定できます。これを行うには、`testData.logFilePath` クエリを使用して IDT コンテキストからログファイルへのパスを取得し、そのパスにファイルを作成し、必要なコンテンツをそのファイルに書き込みます。IDT は、実行中のテストケースに基づいてこのパスを自動的に更新します。テストケースのログファイルを作成しないことを選択すると、そのテストケースのファイルは生成されません。
また、必要に応じて `/logs` フォルダに追加のログファイルを作成するようにテキスト実行可能ファイルをセットアップすることもできます。ファイルが上書きされないように、ログファイル名に一意のプレフィックスを指定することをお勧めします。
## IDT に結果をレポートする
IDT は、テスト結果を `awsiotdevicetester_report.xml` ファイルと `suite-name_report.xml` ファイルに書き込みます。これらのレポートファイルは、`/results//` にあります。両レポートとも、テストスイート実行の結果をキャプチャします。IDT がこれらのレポートに使用するスキーマの詳細については、[IDT テストの結果とログを確認する](idt-review-results-logs.md)を参照してください。
`suite-name_report.xml` ファイルのコンテンツを取得するには、`SendResult` コマンドを使用して、テスト実行が終了する前に、テスト結果を IDT にレポートする必要があります。IDT は、テスト結果を見つけられない場合、テストケースのエラーを発行します。次の Python の抜粋は、テスト結果を IDT に送信するコマンドを示しています。
```
request-variable = SendResultRequest(TestResult(result))
client.send_result(request-variable)
```
API を使用して結果をレポートしない場合、IDT はテストアーティファクトフォルダでテスト結果を検索します。このフォルダのパスは、IDT コンテキストの `testData.testArtifactsPath` フィールドに格納されています。このフォルダで、IDT は、アルファベット順にソートされた最初の XML ファイルをテスト結果として使用します。
テストロジックが JUnit XML 結果を生成する場合は、結果を解析してから API を使用して IDT に送信する代わりに、アーティファクトフォルダ内の XML ファイルにテスト結果を書き込んで、直接 IDT に提供することができます。
この方法を使用する場合は、テストロジックによってテスト結果が正確に要約されていること、および `suite-name_report.xml` ファイルと同じ形式で結果ファイルがフォーマットされていることを確認してください。IDT は、次の例外を除き、提供されたデータの検証を実行しません。
+ IDT は `testsuites` タグのすべてのプロパティを無視します。代わりに、レポートされた他のテストグループ結果からタグのプロパティを計算します。
+ `testsuite` 内に少なくとも 1 つの `testsuites` タグが存在する必要があります。
IDT はすべてのテストケースで同じアーティファクトフォルダを使用し、テスト実行の終了後、次のテスト実行までに結果ファイルを削除しないため、この方法を使用すると、IDT が正しくないファイルを読み取った場合に、誤ったレポートが行われる可能性もあります。IDT が適切な結果を読み取れるように、すべてのテストケースで生成される XML 結果ファイルに同じ名前を使用して、各テストケースの結果を上書きすることをお勧めします。テストスイートのレポート作成に複合的なアプローチ (一部のテストケースには XML 結果ファイルを使用し、他のテストケースには API を使用して結果を送信する) を使用することもできますが、このアプローチはお勧めしません。
## 終了動作を指定する
テキスト実行可能ファイルは、テストケースが障害やエラー結果をレポートした場合でも、常に終了コード 0 で終了するように設定します。ゼロ以外の終了コードは、テストケースが実行されなかったこと、またはテストケース実行可能ファイルが結果を IDT に通知できなかったことを示す場合にのみ使用します。IDT は、0 以外の終了コードを受信すると、テスト実行を妨げるエラーが発生したとしてテストケースをマークします。
IDT は、以下に示すイベントが発生すると、終了前にテストケースに実行の停止を要求 (または想定) することがあります。以下の情報を使用して、テストケースから以下の各イベントを検出するようにテストケース実行可能ファイルを設定します。
**タイムアウト**
テストケースが、`test.json` ファイルで指定されたタイムアウト値よりも長く実行されたときに発生します。テストの実行者が `timeout-multiplier` 引数を使用してタイムアウト乗数を指定すると、IDT はこの乗数を使用してタイムアウト値を計算します。
このイベントを検出するには、IDT\$1TEST\$1TIMEOUT 環境変数を使用します。テストの実行者がテストを起動すると、IDT は IDT\$1TEST\$1TIMEOUT 環境変数の値を計算されたタイムアウト値 (秒単位) に設定し、その変数をテストケース実行可能ファイルに渡します。この変数の値を読み取って適切なタイマーを設定します。
**割り込み**
テストの実行者が IDT に割り込むと発生します。例えば、Ctrl\$1C を押した時です。
ターミナルはすべての子プロセスに通知を伝播するため、割り込み通知を検出する通知ハンドラをテストケースに簡単に設定できます。
または、API を定期的にポーリングして、`PollForNotifications` API 応答の `CancellationRequested` ブール値をチェックできます。IDT は割り込み通知を受信すると、`CancellationRequested` ブールの値を `true` に設定します。
**最初の失敗時に停止する**
現在のテストケースと並行して実行中のテストケースが失敗し、テストの実行者が `stop-on-first-failure` 引数を使用して、障害の発生時に IDT が実行を停止するように設定しているときに発生します。
このイベントを検出するには、`PollForNotifications` API を定期的にポーリングして、API レスポンスの `CancellationRequested` ブールの値をチェックします。IDT は、最初の障害発生時に停止するように設定されている場合、障害に遭遇すると、`CancellationRequested` ブールの値を `true` に設定します。
これらのいずれかのイベントが発生すると、IDT は現在実行中のテストケースの実行が終了するまで 5 分間待機します。実行中のすべてのテストケースが 5 分以内に終了しない場合、IDT は各プロセスを強制的に停止させます。IDT は、プロセスの終了前にテスト結果を受け取らなかった場合、テストケースをタイムアウトしたとしてマークします。ベストプラクティスとして、いずれかのイベントが発生したときは、テストケースが以下のアクションを実行するようにします。
1. 通常のテストロジックの実行を停止する。
1. テスト対象デバイスのテストアーティファクトなど、すべての一時的なリソースをクリーンアップする。
1. テスト結果 (テストの失敗やエラーなど) を IDT にレポートする。
1. 終了する。