Microbenchmark インストルメンテーション引数

次の計測引数を指定して、Microbenchmark の動作を設定します。これらは Gradle の設定に追加することも、コマンドラインから計測を実行する際に直接適用することもできます。Android Studio とコマンドラインのすべてのテスト実行にこれらの引数を設定するには、testInstrumentationRunnerArguments に追加します。

android {
    defaultConfig {
        // ...
        testInstrumentationRunnerArguments["androidx.benchmark.dryRunMode.enable"] = "true"
    }
}

Android Studio からベンチマークを実行するときに計測引数をセットアップすることもできます。引数を変更する手順は次のとおりです。

1. [Edit] をクリックしてから、編集する設定を選択して、実行設定を編集します。

   

   図 1.実行設定を編集する

2. [Instrumentation arguments] フィールドの横にある をクリックして、インストルメンテーション引数を編集します。

   

   図 2.インストルメンテーション引数の編集

3. をクリックし、必要なインストルメンテーション引数を追加します。

   

   図 3.インストルメンテーション引数の追加

コマンドラインからベンチマークを実行する場合は、-P android.testInstrumentationRunnerArguments.[name of the argument] を使用します。

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.profiling.mode=StackSampling

am インストルメンテーション コマンドを直接呼び出す場合は（CI テスト環境で発生する可能性があります）、-e を使用して引数を am instrument に渡します。

adb shell am instrument -e androidx.benchmark.profiling.mode StackSampling -w com.example.macrobenchmark/androidx.benchmark.junit4.AndroidBenchmarkRunner

CI でベンチマークを構成する方法については、CI でベンチマークを実行するをご覧ください。

additionalTestOutputDir

JSON ベンチマーク レポートとプロファイリング結果を保存するデバイス上の場所を指定します。

• 引数タイプ: ファイルパスの文字列
• デフォルト設定: テスト APK の外部ディレクトリ

androidx.benchmark.dryRunMode.enable

ベンチマークを 1 回のループで実行して、正常に機能するかどうかを検証できます。

これは次のことを意味します。

• 構成エラーは適用されません（エミュレータで定期的な正確性テストを実行しやすくするためなど）。
• ベンチマークはウォームアップなしで 1 つのループのみを実行します。
• ランタイムを短縮するために、測定値とトレースがキャプチャされない

これにより、ビルドと測定の正確性よりも、テスト スループットとベンチマーク ロジックの検証を重視して最適化されます。

• 引数タイプ: ブール値
• デフォルト設定: false

androidx.benchmark.iterations

時間ベースの目標イテレーション数をオーバーライドして、処理量に一貫性を持たせます。これは通常、プロファイリングを有効にして、異なる実装または実行を比較する際に、プロファイリング トレース内で一定量の作業が実行されるように設定したい場合にのみ有用です。それ以外のシナリオでは、測定の精度や安定性が低下する可能性があります。

• 引数のタイプ: 整数
• デフォルト設定: 指定なし

androidx.benchmark.junit4.SideEffectRunListener

ベンチマークの実行中に無関係なバックグラウンド処理が実行されると、一貫性のあるベンチマーク結果が得られない可能性があります。

ベンチマーク実行中のバックグラウンド処理を無効にするには、listener インストルメンテーション引数のタイプを androidx.benchmark.junit4.SideEffectRunListener に設定します。

• 引数タイプ: 文字列
• 利用可能なオプション:
  • androidx.benchmark.junit4.SideEffectRunListener
• デフォルト設定: 指定なし

androidx.benchmark.output.enable

結果の JSON ファイルを外部ストレージに書き込めるようにします。

• 引数タイプ: ブール値
• デフォルト設定: true

androidx.benchmark.profiling.mode

ベンチマークの実行中にトレース ファイルをキャプチャできるようにします。利用可能なオプションについては、Microbenchmark をプロファイリングするをご覧ください。

• 引数のタイプ: 文字列
• 利用可能なオプション:
  • MethodTracing
  • StackSampling
  • None
• デフォルト設定: None

androidx.benchmark.suppressErrors

エラーのカンマ区切りのリストを受け入れて、警告に変換できます。

• 引数のタイプ: 文字列のリスト
• 利用可能なオプション:
  • DEBUGGABLE
  • LOW-BATTERY
  • EMULATOR
  • CODE-COVERAGE
  • UNLOCKED
  • SIMPLEPERF
  • ACTIVITY-MISSING
• デフォルト設定: 空のリスト

androidx.benchmark.startupMode.enable（非推奨）

注: アプリ起動のベンチマークには、Macrobenchmark ライブラリの方が適しています。

起動時のベンチマーク コードをサポートするようにループ動作を再設定します。ベンチマークは、ウォームアップ ループなしで 10 回の測定で実行されます。マイクロ ベンチマークのオーバーヘッドを最小限に抑えるために、ループ平均化は無効になっています。

• 引数タイプ: ブール値
• デフォルト設定: false