androidtestrunner ツール

はじめに

androidtestrunner ツールは、Androidデバイスおよびエミュレータ上でQt Testを実行します。このツールは、APKのインストール管理、テストの実行、結果の取得など、テスト実行に必要な手順を自動化します。

androidtestrunner を使用する前に、CMake または qmake を使用して Qt Test プロジェクトの設定が完了していることを確認してください。

仕組み

1. まず、APK ビルドコマンドを実行して、テストに必要な APK を生成します。
2. その後、テストアプリをターゲットデバイスにインストールして起動し、テストプロセスを開始します。
3. テスト結果は、デバイス上のアプリのデータディレクトリに書き込まれ、包括的なテスト出力が確実に取得されます。
4. テストが終了すると、ランナーは結果ファイルの隣に終了コードファイルを書き込みます。
5. この段階で、androidtestrunner はデバイスからこれらの結果ファイルを取得し、終了コードを調べて失敗の有無を確認します。
6. 問題が検出された場合、アプリ の logcat ログ（クラッシュの原因となる可能性のあるスタックトレースを含む）が即座に出力されます。このログは、各フレームのファイル名と行番号がわかるように整形されています。さらに、テストの実行中に「アプリケーションが応答しない（ANR）」というイベントが発生した場合、そのログも取得して報告します。

統合体験を向上させるため、テストランナーは、テストランナープロセスのホスト環境からアプリへ QT または Qt Test 環境変数を伝播させ、一貫性とシームレスなテストワークフローを確保します。

テストラッパーを使用したテストの実行

Qtは、各Androidテスト（テストターゲットの名前に基づいて命名）とともに、ターゲットごとのラッパースクリプトを生成します。このスクリプトは、適切なパスを指定してandroidtestrunner を呼び出し、追加の引数をテストバイナリに渡します。以下の例では、特定のエミュレータ上でtst_android を実行し、Qt環境変数を渡し、testAssets テストケースのみを実行しています：

ANDROID_SERIAL=emulator-5554 QT_DEBUG_PLUGINS=1 ./tst_android testAssets

結果の取得

デフォルトでは、テストの出力（stdout）が明示的に無効化されていない限り、テストの実行中に結果がホストに出力されます。テストの実行後、明示的に要求されたテストファイルは、それぞれの形式で指定された出力パスに取得されます。

Qt Test フレームワークの詳細については、「Qt Test の概要」を参照してください。

使用方法

androidtestrunner を実行するための基本的な構文は次のとおりです：

androidtestrunner [ARGUMENTS] -- [TESTARGS]

特定のデバイス/エミュレータでテストを実行するには、--serial <serial> を指定するか、adb 環境変数をANDROID_SERIAL またはANDROID_DEVICE_SERIAL に設定します。明示的なオプションが優先されます。

必須の引数

テストランナーは、常に以下の引数が渡されることを想定しています:

• --path <build-path>: Android Gradle パッケージがビルドされるパス。通常は<build-dir>/android-build-<target> です。
• --make <build-command>: テスト用APKをビルドするために使用されるコマンド。例:cmake --build <build-dir> --target <target>_make_apk 。

  注： この引数は、テストランナーによって複数の引数として扱われるのではなく、「--make 」引数の値として認識されるよう、引用符で囲んで渡してください 。

• 以下のいずれか：
  • --apk <apk-path>: ビルドコマンドによって生成され、デバイスにインストールされたテスト APK へのパス。
  • --aab <aab-path>: テスト用 AAB へのパス。--bundletool が必要です。両方のオプションを同時に設定することはできず、いずれのオプションも 1 回以上指定することはできません。

オプション引数

以下のオプション引数を指定することもできます：

• --bundletool <path>: Androidのbundletool JARファイルへのパス。--aab を使用する場合に必須です。
• --manifest <path>: カスタムAndroidManifest.xml のパス。デフォルトでは、ビルドパスまたはそのapp/ サブディレクトリ配下で検出されたファイルが使用されます。
• --adb <adb-path>: カスタム ADB コマンドのパスを指定します。デフォルトは、システムの `$PATH` にある `adb ` のパスです。
• --serial <serial>: ターゲットとするAndroidデバイスのシリアル番号。ANDROID_SERIAL およびANDROID_DEVICE_SERIAL の設定を上書きします。
• --activity <activity-name>: 実行するカスタムアクティビティを指定します。デフォルトは、AndroidManifest.xml で定義されている最初のアクティビティです。
• --timeout <seconds>: テスト実行のタイムアウトを設定します。デフォルトは 600 秒（10 分）です。
• --pre-test-adb-command <command>: インストール後、テスト実行前に adb<command> を実行します。複数回指定可能です。
• --skip-install-root: ビルドコマンドがmake-family ツール（make 、gmake 、nmake 、mingw32-make 、jom ；大文字小文字を区別せずに照合）である場合、--make に自動的に付加されるINSTALL_ROOT=<path> install サフィックスを抑制します。cmake 、ninja 、またはその他のビルドドライバーに対してはサフィックスが付加されないため、このオプションはリストされたツールでのみ有効です。
• --ndk-stack <command-path>: クラッシュスタックトレースのシンボル化を行うndk-stackツールのパスを指定します。デフォルトは、$ANDROID_NDK_ROOT にあるツールパスです。
• --show-logcat: テストの成否にかかわらず、logcatの出力を標準出力（stdout）に表示します。main、system、crashの各バッファを読み取り、ANRが検出された場合はsystem_server の行を含めます。
• --verbose: 詳細な出力を表示します。
• -- <arguments>: ダッシュの後の引数をすべてテスト引数として渡します。
• --help: ヘルプ情報を表示します。

使用例

以下は、tst_android テストを実行し、testAssets のテストケースのみを実行する例です：

androidtestrunner \
    --path ~/tst_android/build/android-build-tst_openssl \
    --make "cmake --build ~/tst_android/build --target apk" \
    --apk ~/tst_android/build/android-build-tst_openssl/tst_openssl.apk \
    testAssets