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 instrumentation 指令 (可能是在 CI 測試環境中)，請使用 -e 將引數傳遞至 am instrument：

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

如要進一步瞭解如何在 CI 中設定基準測試，請參閱「持續整合中的基準測試」一文。

androidx.benchmark.cpuEventCounter.enable (實驗性)

計算 androidx.benchmark.cupEventCounter.events 中指定的 CPU 事件。需要根層級存取權。

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

androidx.benchmark.cpuEventCounter.events (實驗性)

指定要計算的 CPU 事件類型。如要使用這個引數，androidx.benchmark.cpuEventCounter.enable 必須設為 true。

• 引數類型：以半形逗號分隔的字串清單
• 可用選項：
  • Instructions
  • CPUCycles
  • L1DReferences
  • L1DMisses
  • BranchInstructions
  • BranchMisses
  • L1IReferences
  • L1IMisses
• 預設為： Instructions、CpuCycles、BranchMisses

androidx.benchmark.dryRunMode.enable

在單一迴圈中執行基準測試，確認測試可正常運作。

因此：

• 不會強制執行設定錯誤 (例如，方便在模擬器上執行一般正確性測試)
• 基準測試只會執行單一迴圈，不會暖機
• 系統不會擷取評估結果和追蹤記錄，以縮短執行時間

這項設定會優先考量測試總處理量和驗證基準測試邏輯，而非建構和評估正確性。

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

androidx.benchmark.killExistingPerfettoRecordings

根據預設，Benchmark 會在啟動新追蹤記錄時，終止所有現有的 Perfetto (系統追蹤記錄)，以減少干擾。如要停用這項行為，請傳遞 false。

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

androidx.benchmark.output.enable

可將結果 JSON 檔案寫入外部儲存空間。

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

androidx.benchmark.profiling.mode

允許在執行基準測試時擷取追蹤記錄檔案。請參閱「剖析 Microbenchmark」，瞭解可用選項。

請注意，部分 Android OS 版本不支援方法追蹤，且不會影響後續的測量結果。為避免這種情況，微量基準測試會擲回例外狀況，因此請使用預設引數，僅在安全無虞時擷取方法追蹤記錄。請參閱問題 #316174880。

• 引數類型：字串
• 可用選項：
  • MethodTracing
  • StackSampling
  • None
• 預設值：MethodTracing 的安全版本，只有在裝置不會受到影響的情況下，才會擷取方法追蹤記錄。

androidx.benchmark.suppressErrors

接受以半形逗號分隔的錯誤清單，並轉換成警告。

• 引數類型：字串清單
• 可用選項：
  • DEBUGGABLE
  • LOW-BATTERY
  • EMULATOR
  • CODE-COVERAGE
  • UNLOCKED
  • SIMPLEPERF
  • ACTIVITY-MISSING
• 預設為：空白清單

additionalTestOutputDir

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

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

listener

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

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

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