撰寫巨集基準

使用 Macrobenchmark 程式庫測試應用程式的大型用途，包括應用程式啟動及複雜的 UI 操控方式，例如捲動 RecyclerView 或執行動畫。如要測試程式碼較小的區域，請參閱 microbenchmark 程式庫。

程式庫會將基準化結果輸出至 Android Studio 主控台和 JSON 檔案，其中包含更多詳細資料。這個套件也提供您可以在 Android Studio 中載入及分析的追蹤檔。

您也可以在持續整合 (CI) 環境中使用 Macrobenchmark 程式庫。詳情請參閱持續整合的基準。

專案設定

建議您將 Macrobenchmark 與最新版的 Android Studio (Bumblebee 2021.1.1 以上版本) 搭配使用，因為該 IDE 版本中的新功能已與 Macrobenchmark 整合。

設定 Macrobenchmark 模組

巨集基準需要獨立於應用程式程式碼之外的 com.android.test 模組，負責執行評估應用程式的測試。

Bumblebee (或更新版本)

您可以在 Android Studio Bumblebee 2021.1.1 中使用範本來簡化 Macrobenchmark 模組設定。基準化模組範本會在專案中自動建立模組，以評估由應用程式模組建立的應用程式，包括新創公司基準範例。

如要使用模組範本建立新模組，請執行下列步驟：

在 Android Studio 的「專案」面板中，以滑鼠右鍵按一下您的專案或模組，然後按一下「新增」>「模組」。
從「範本」窗格中選取「基準」。
您可以自訂目標應用程式 (要基準化的應用程式) 以及新巨集基準模組的套件和模組名稱。
按一下「完成」。

Arctic Fox

您需要在 Arctic Fox 上建立程式庫模組，並將其轉換為測試模組。

在 Android Studio 的「專案」面板中，以滑鼠右鍵按一下您的專案或模組，然後按一下「新增」>「模組」。
在「範本」窗格中選取「Android 程式庫」。
輸入 macrobenchmark 做為模組名稱。
將「Minimum SDK」(SDK 最低版本) 設為「API 23: Android M」 (API 23：Android M)
按一下「完成」。

修改 Gradle 檔案

自訂 Macrobenchmark 模組的 build.gradle 如下所示：

將外掛程式從 com.android.library 變更為 com.android.test。
```
apply plugin 'com.android.test'
```

在 android {} 區塊中加入其他必要的測試模組屬性：

Groovy

android {
    // ...
    // Note that your module name may have different name
    targetProjectPath = ":app"
    // Enable the benchmark to run separately from the app process
    experimentalProperties["android.experimental.self-instrumenting"] = true

    buildTypes {
        // declare a build type to match the target app's build type
        benchmark {
            isDefault = true
            debuggable = true
            signingConfig = debug.signingConfig
        }
    }
}build.gradle

Kotlin

android {
    // ...
    // Note that your module name may have different name
    targetProjectPath = ":app"
    // Enable the benchmark to run separately from the app process
    experimentalProperties["android.experimental.self-instrumenting"] = true

    buildTypes {
        // declare a build type to match the target app's build type
        create("benchmark") {
            isDebuggable = true
            signingConfig = signingConfigs.getByName("debug")
        }
    }
}

將所有名為 testImplementation 或 androidTestImplementation 的依附元件變更為 implementation。

新增對 Macrobenchmark 程式庫的依附元件：

implementation 'androidx.benchmark:benchmark-macro-junit4:1.1.0-beta03'

僅允許 benchmark 建構作業的模組類型。在 android{} 區塊之後，但在 dependencies{} 區塊之前，加上：

Groovy

androidComponents {
    beforeVariants(selector().all()) {
        // enable only the benchmark buildType, since we only want to measure close to release performance
        enabled = buildType == 'benchmark'
    }
}build.gradle

Kotlin

androidComponents {
    beforeVariants {
        // enable only the benchmark buildType, since we only want to measure close to release performance
        it.enable = it.buildType == "benchmark"
    }
}

簡化目錄結構。
在 com.android.test 模組中，所有測試都只有一個來源目錄。刪除其他來源目錄，包括 src/test 和 src/androidTest。

設定應用程式

如要對應用程式進行參照 (稱為巨集基準的目標)，應用程式必須為 profileable，以便讀取詳細的追蹤記錄資訊。在應用程式的 AndroidManifest.xml 的 <application> 標記中啟用這項功能：

<!-- enable profiling by macrobenchmark -->
<profileable
    android:shell="true"
    tools:targetApi="q" />AndroidManifest.xml

盡可能將基準化應用程式設定為接近發布版本 (或正式版)。請將其設為無法進行偵錯，最好是開啟壓縮功能，藉此提升效能。通常，您只要建立發布版本的變化版本，就能以相同方式執行發布作業，不過系統會透過偵錯金鑰在本機簽署。您也可以使用 initWith 指示 Gradle 進行以下操作：

Groovy

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
    }

    benchmark {
        initWith buildTypes.release
        signingConfig signingConfigs.debugbuild.gradle

Kotlin

buildTypes {
    getByName("release") {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
    }

    create("benchmark") {
        initWith(getByName("release"))
        signingConfig = signingConfigs.getByName("debug")
    }
}

執行 Gradle 同步處理、開啟左側的「Build Variants」面板，然後選取應用程式和 Macrobenchmark 模組的基準變化版本。確保執行基準會建構及測試應用程式的正確版本：

設定多模組應用程式

如果您的應用程式有多個 Gradle 模組，您必須確保建構指令碼知道要編譯哪個建構變化版本。在未設定的情況下，新增的 benchmark 建構作業類型會導致建構失敗，並顯示下列錯誤訊息：

> Could not resolve project :shared.
     Required by:
         project :app
      > No matching variant of project :shared was found.

如要解決這個問題，請將 matchingFallbacks 屬性加入 :macrobenchmark 和 :app 模組的 benchmark buildType 中。您的其他 Gradle 模組可以具備和之前相同的設定。

Groovy

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
}

Kotlin

create("benchmark") {
    initWith(getByName("release"))
    signingConfig = signingConfigs.getByName("debug")

    matchingFallbacks += listOf('release')
}

在專案中選取建構變化版本時，請為 :app 和 :macrobenchmark 模組選擇 benchmark，如為應用程式中的任何其他模組，請選擇 release，如下方所示下圖：

詳情請參閱變體感知依附元件管理。

建立巨集基準類別

基準測試是透過 Macrobenchmark 程式庫中的 MacrobenchmarkRule JUnit4 規則 API 提供。其中包含 measureRepeated 方法，讓您指定如何針對目標應用程式執行及執行基準。

您必須指定目標應用程式的 packageName、要評估的 metrics，以及要執行基準的 iterations。

Kotlin

@LargeTest
@RunWith(AndroidJUnit4::class)
class SampleStartupBenchmark {
    @get:Rule
    val benchmarkRule = MacrobenchmarkRule()

    @Test
    fun startup() = benchmarkRule.measureRepeated(
        packageName = TARGET_PACKAGE,
        metrics = listOf(StartupTimingMetric()),
        iterations = 5,
    ) {
        // starts default launch activity
        startActivityAndWait()
    }
}SampleStartupBenchmark.kt

Java

@LargeTest
@RunWith(AndroidJUnit4.class)
public class SampleStartupBenchmark {
    @Rule
    public MacrobenchmarkRule benchmarkRule = new MacrobenchmarkRule();

    @Test
    public void startup() {
        benchmarkRule.measureRepeated(
            /* packageName */ TARGET_PACKAGE,
            /* metrics */ Arrays.asList(new StartupTimingMetric()),
            /* iterations */ 5,
            /* measureBlock */ scope -> {
                // starts default launch activity
                scope.startActivityAndWait();
                return Unit.INSTANCE;
            }
        );
    }
}

如需自訂基準的所有選項，請參閱自訂基準一節。

執行基準測試

在 Android Studio 中執行測試，以測量應用程式在裝置上的效能。基準的測試方式，與使用其他類別或測試方法執行其他 @Test 的方式相同，如下所示：

您也可以透過執行 ConnectedCheck 指令，在指令列執行 Gradle 模組中的所有基準：

./gradlew :macrobenchmark:connectedCheck

或執行單一測試：

./gradlew :macrobenchmark:connectedCheck -P android.testInstrumentationRunnerArguments.class=com.example.macrobenchmark.startup.SampleStartupBenchmark#startup

如要瞭解如何在持續整合服務中執行及監控基準，請參閱 CI 基準化一節。

基準結果

基準測試執行完畢後，會直接顯示在 Android Studio 中，系統也會在 JSON 檔案中輸出 CI 的輸出資料。每項經過評估的疊代作業都會擷取個別系統追蹤記錄。如要開啟「結果結果」追蹤記錄，請按一下「測試結果」窗格中的任一連結，如下圖所示。

載入追蹤記錄時，Android Studio 會提示您選取要分析的程序。應用程式會預先填入目標應用程式程序：

追蹤檔載入完成後，Studio 會在 CPU 分析器工具中顯示結果：

手動存取追蹤檔

如果您使用的是舊版 Android Studio (掌握 Arctic Fox 2020.3.1 版本) 或想使用 Perfetto 工具分析追蹤檔，步驟。Perfetto 可讓您查看在追蹤記錄期間裝置上透過裝置處理的所有程序，而 Android Studio 的 CPU 分析器會將檢查限制為單一程序。

如果您從 Android Studio 叫用測試或使用 Gradle 指令列，追蹤檔會自動從裝置複製到主機。這些程式碼會在主機機器上寫入：

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/TrivialStartupBenchmark_startup[mode=COLD]_iter002.perfetto-trace

在主機系統上取得追蹤檔後，在選單中依序點選「檔案」 > 「開啟」，即可透過 Android Studio 開啟追蹤檔。如上節所示的分析器工具檢視畫面。

設定錯誤

如果應用程式設定錯誤 (可偵錯或無法剖析)，Macrobenchmark 會傳回錯誤，而不是回報不正確或不完整的測量結果。您可以使用 androidx.benchmark.suppressErrors 引數略過這些錯誤。

此外，系統在評估模擬器或低電量裝置時也會回報錯誤，因為這樣可能會影響核心可用性和時鐘速度。

自訂基準

measureRepeated 函式可接受各種參數，而這些參數會影響程式庫收集的指標、應用程式的啟動與編譯方式，或是基準測試將執行的疊代次數。

擷取指標

指標是指擷取基準資訊的主要類型資訊。支援的選項包括、StartupTimingMetric 和。如要進一步瞭解相關資訊，請參閱擷取指標頁面。

使用自訂事件改善追蹤記錄資料

您可以透過自訂追蹤記錄事件，對應用程式進行檢測；透過其他追蹤記錄報表查看，有助您找出應用程式特有的問題。如要進一步瞭解如何建立自訂追蹤事件，請參閱定義自訂事件指南。

CompilationMode

巨集基準可指定 CompilationMode，這會定義應在 DEX 位元組代碼 (APK 中的位元組碼格式) 預先編譯至機器程式碼 (類似 pre-complied 的應用程式數量-編譯完成的 C++)。

根據預設，巨集基準是透過 CompilationMode.DEFAULT 執行，後者會在 Android 7 (API 層級 24) 以上版本中安裝基準設定檔 (如果有的話)。如果您使用的是 Android 6 (API 層級 23) 以下的版本，編譯模式會將所有 APK 編譯為預設系統行為。

如果目標應用程式包含基準設定檔和 ProfileInstaller 程式庫，您就可以安裝基準設定檔。

在 Android 7 以上版本中，您可以自訂 CompilationMode 來影響裝置端預先編譯的資料量，會模擬不同時間的先進 (AOT) 編譯或 JIT 快取功能。請參閱與CompilationMode.Full。

這項功能以 ART 編譯指令為基礎。每個基準會在清除資料前清除設定檔資料，以確保基準之間的非干擾情況。

啟動模式

如要執行活動開始，您可以傳遞預先定義的啟動模式 (COLD、WARM 或 HOT 其中之一)。這個參數會改變活動啟動時的方式，以及測試開始的流程狀態。

如要進一步瞭解新創公司的類型，請參閱 Android Vitals 啟動說明文件。

範例

範例專案是 GitHub 上的 android/performance-samples 存放區的一部分。

提供意見

如要回報或提交 Jetpack Macrobenchmark 的功能要求，請參閱公開問題追蹤工具。