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.cpuEventCounter.enable (實驗性)

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

• 引數類型：布林值
• 預設值：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.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」，瞭解可用選項。

請注意，某些 Android OS 版本不支援方法追蹤，否則後續測量會受到影響。微量基準程式會擲回例外狀況來避免這種情況，因此請只在安全的情況下使用預設引數擷取方法追蹤記錄。請參閱 問題 #316174880。

• 引數類型：字串
• 可用選項：
  • MethodTracing
  • StackSampling
  • None
• 預設為：MethodTracing 的安全版本，僅在裝置可在不影響評估的情況下擷取方法追蹤記錄。

androidx.benchmark.suppressErrors

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

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