Macrobenchmark 檢測引數

使用下列檢測引數設定程式庫的行為。您可以將這些引數新增至 Gradle 設定，或是在透過指令列執行檢測時直接套用。如要為所有 Android Studio 和指令列測試執行作業設定這些引數，請將引數新增至 testInstrumentationRunnerArguments：

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

透過 Android Studio 執行基準測試時，也可以設定檢測引數。如要變更引數，請執行下列操作：

如果您要透過指令列執行宏型基準測試，請使用 -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

可在單一迴圈中執行基準測試，確認其是否正常運作。這個引數可與一般測試搭配使用，做為驗證的一部分。

• 引數類型：布林值
• 預設為：false

androidx.benchmark.enabledRules

讓篩選器可以只執行一個類型的測試，例如基準設定檔產生測試或 Macrobenchmark 測試。另外也支援以半形逗號分隔的清單。

• 引數類型：字串
• 可用選項：
  • Macrobenchmark
  • BaselineProfile
• 預設為：未指定

androidx.benchmark.junit4.SideEffectRunListener

在基準測試執行期間，如果您執行不相關的背景工作，可能會取得不一致的基準測試結果。

如要在基準測試期間停用背景工作，請將 listener 檢測引數類型設為 androidx.benchmark.junit4.SideEffectRunListener。

• 引數類型：字串
• 可用選項：
  • androidx.benchmark.junit4.SideEffectRunListener
• 預設為：未指定

androidx.benchmark.fullTracing.enable

啟用 androidx.tracing.perfetto 追蹤點，例如 Jetpack Compose 組合追蹤。

您需要設定專案，才能從基準擷取組合追蹤記錄。詳情請參閱「使用 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 的設定執行基準測試。可進行偵錯的引數會影響執行速度，意味著基準測試改善項目可能無法繼承到實際使用者體驗，也可能降低版本效能。

  • LOW-BATTERY

    電力不足時，裝置通常會降低效能以節省電池電力，例如停用大型核心。即使裝置接上電源也會發生這種情形。除非您是刻意降低效能來分析應用程式，否則請勿隱藏這項錯誤。

  • EMULATOR

    EMULATOR 錯誤表示基準測試是在模擬器上執行，不是代表實際使用者的裝置。模擬器基準測試改善項目可能無法繼承至實際使用者體驗，也可能降低實體裝置的效能。您應改用實體裝置進行基準測試。如要隱藏這項錯誤，請務必謹慎操作。

  • NOT-PROFILEABLE

    目標套件 $packageName 在未設定 <profileable shell=true> 的情況下執行。Android 10 和 11 必須設定 Profileable，Macrobenchmark 才能從目標程序擷取詳細的追蹤記錄資訊，例如應用程式或程式庫中定義的系統追蹤區段。如要隱藏這項錯誤，請務必謹慎操作。

  • METHOD-TRACING-ENABLED

    要執行基準測試的應用程式，其 Macrobenchmark 執行作業已啟用方法追蹤。這會導致 VM 的執行速度變慢，因此請只考量追蹤記錄檔中相關條件的指標，例如比較首次執行和第二次執行的速度。如要針對採用不同方法追蹤選項的版本比較基準測試結果，則隱藏這項錯誤可能導致結果不準確。

• 預設為：空白清單

additionalTestOutputDir

設定 JSON 基準報告和剖析結果儲存在裝置上的位置。

• 引數類型：路徑字串
• 預設為：測試 APK 的外部目錄