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

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

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

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

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

./gradlew :benchmark:connectedAndroidTest -P android.testInstrumentationRunnerArguments.androidx.benchmark.enabledRules=BaselineProfile

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

adb shell am instrument -e androidx.benchmark.enabledRules BaselineProfile -w com.example.macrobenchmark/androidx.test.runner.AndroidJUnitRunner

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

androidx.benchmark.compilation.enabled

ベンチマークの各反復処理間のコンパイルを無効にできます。デフォルトでは、ターゲット アプリは、measureRepeated に渡される CompilationMode に準拠するように、各ベンチマーク間で再インストールされ、再コンパイルされます。このパラメータを無効にすると、再インストールとコンパイルの両方をスキップできます（テストスイートを実行する前にターゲット アプリを完全にコンパイルし、その完全にコンパイルされたターゲットに対してすべてのベンチマークを実行する場合など）。

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

androidx.benchmark.dryRunMode.enable

ベンチマークを 1 回のループで実行して、正常に機能するかどうかを検証できます。検証の一環として、定期的なテストで使用できます。

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

androidx.benchmark.enabledRules

1 種類のテスト（ベースライン プロファイル生成または Macrobenchmark テスト）のみにフィルタリングを実行できます。カンマ区切りのリストもサポートされます。

• 引数のタイプ: 文字列
• 利用可能なオプション:
  • Macrobenchmark
  • BaselineProfile
• デフォルト設定: 指定なし

androidx.benchmark.junit4.SideEffectRunListener

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

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

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

androidx.benchmark.fullTracing.enable

Jetpack Compose のコンポジションのトレースなどの androidx.tracing.perfetto トレースポイントを有効にします。

ベンチマークからコンポジションのトレースをキャプチャできるように、プロジェクトをセットアップする必要があります。詳細については、Jetpack Macrobenchmark を使用してトレースをキャプチャするをご覧ください。

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

androidx.benchmark.profiling.mode

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

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

androidx.benchmark.startupProfiles.enable

ベンチマーク実行時に起動プロファイルの生成を無効にできます。

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

androidx.benchmark.suppressErrors

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

• 引数のタイプ: 文字列のリスト

• 利用可能なオプション:

  • DEBUGGABLE

    DEBUGGABLE エラーは、ターゲット パッケージのマニフェストに debuggable=true と設定された状態で実行されていることを示しています。これによりデバッグ機能がサポートされ、ランタイム パフォーマンスが著しく低下します。このエラーを回避するには、debuggable=false を使用してベンチマークを実行します。debuggable 引数は、ベンチマークの改善が実際のユーザー エクスペリエンスに反映されなかったり、リリース パフォーマンスが低下したりする可能性があるという点で、実行速度に影響します。

  • LOW-BATTERY

    バッテリー残量が少ない場合、一般にデバイスは、大きなコアを無効にするなど、パフォーマンスを低下させてバッテリー残量を節約します。これは、デバイスが電源に接続されている場合でも発生します。パフォーマンスを低下させて意図的にアプリのプロファイリングを行っている場合にのみ、このエラーを除外します。

  • EMULATOR

    EMULATOR エラーは、ベンチマークがエミュレータで実行されていることを示しています。これは、実際のユーザー デバイスを表すものではありません。エミュレータでベンチマークが改善しても、実際のユーザー エクスペリエンスには反映されない場合や、実際のデバイスのパフォーマンスが低下する場合があります。代わりに実機を使用してベンチマークを行う必要があります。このエラーは、細心の注意を払って除外します。

  • NOT-PROFILEABLE

    ターゲット パッケージ $packageName が、<profileable shell=true> に設定されていない状態で実行されています。Android 10 と 11 では、Macrobenchmark がターゲット プロセスから詳細なトレース情報（アプリやライブラリで定義されたシステム トレース セクションなど）をキャプチャできるようにするために profileable が必要になります。このエラーは、細心の注意を払って除外します。

  • METHOD-TRACING-ENABLED

    ベンチマーク対象のアプリで Macrobenchmark を実行すると、メソッド トレースが有効になります。この場合、VM の実行速度が通常より遅くなるため、トレース ファイルの指標は相対的な観点でのみ考慮します（初回の実行速度と 2 回目の実行速度を比較するなど）。このエラーを除外すると、メソッド トレース オプションが異なるビルドのベンチマークを比較した場合に、結果が不正確になる可能性があります。

• デフォルト設定: 空のリスト

additionalTestOutputDir

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

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