撰寫 Macrobenchmark

Stay organized with collections Save and categorize content based on your preferences.

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

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

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

您可使用 Macrobenchmark 產生基準設定檔。請按照以下指南設定 Marcobenchmark 程式庫,然後建立基準設定檔

專案設定

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

設定 Macrobenchmark 模組

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

Bumblebee (或更新版本)

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

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

  1. 在 Android Studio 的「Project」 面板中,於專案或模組上按一下滑鼠右鍵,然後依序點選「New」>「Module」

  2. 從「Templates」(範本) 窗格中選取「Benchmark」(效能評定)

  3. 您可以自訂目標應用程式 (要效能評定的應用程式) 以及新的 Macrobenchmark 模組的套件和模組名稱。

  4. 按一下「Finish」(完成)

效能評定模組範本

Arctic Fox

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

  1. 在 Android Studio 的「Project」 面板中,於專案或模組上按一下滑鼠右鍵,然後依序點選「New」>「Module」
  2. 在「Templates」(範本) 窗格中選取「Android Library」(Android 程式庫)
  3. 輸入 macrobenchmark 做為模組名稱。
  4. 將「Minimum SDK」(SDK 最低版本) 設為 「API 23: Android M」 (API 23:Android M)
  5. 按一下「Finish」(完成)

設定新的程式庫模組

修改 Gradle 檔案

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

  1. 將外掛程式從 com.android.library 變更為 com.android.test
    apply plugin 'com.android.test'
  2. 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 {
                debuggable = true
                signingConfig = debug.signingConfig
            }
        }
    }
      

    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")
            }
        }
    }
      

  3. 將所有名為 testImplementationandroidTestImplementation 的依附元件變更為 implementation
  4. 新增對 Macrobenchmark 程式庫的依附元件:
    implementation 'androidx.benchmark:benchmark-macro-junit4:1.1.0-rc02'
  5. 僅允許 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'
        }
    }
      

    Kotlin

    androidComponents {
        beforeVariants {
            // enable only the benchmark buildType, since we only want to measure close to release performance
            it.enable = it.buildType == "benchmark"
        }
    }
      
  6. 簡化目錄結構。

    com.android.test 模組中,所有測試都只有一個來源目錄。刪除其他來源目錄,包括 src/testsrc/androidTest

設定應用程式

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

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

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

Groovy

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

    benchmark {
        initWith buildTypes.release
        signingConfig signingConfigs.debug

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 類別

效能評定測試是透過 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,
        setupBlock = {
            // Press home button before each run to ensure the starting activity isn't visible.
            pressHome()
        }
    ) {
        // starts default launch activity
        startActivityAndWait()
    }
}

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 的方式相同,如下所示:

在測試類別旁執行虛線動作的 Macrobenchmark

您也可以透過執行 ConnectedCheck 指令,在指令列執行 Gradle 模組中的所有效能評定:

./gradlew :macrobenchmark:connectedCheck

或執行單一測試:

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

如要瞭解如何在持續整合服務中執行及監控效能評定,請參閱「CI 效能評定」一節。

效能評定結果

效能評定執行完畢後,指標會直接顯示在 Android Studio 中,也會在 JSON 檔案中列為 CI 使用情形的輸出內容。每項經過評估的疊代作業都會擷取個別系統追蹤記錄。如要開啟結果追蹤記錄,請按一下「Test Results」窗格中的任一連結,如下圖所示。

Macrobenchmark 啟動結果

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

選取工作室追蹤程序

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

Studio Trace

手動存取追蹤檔

如果您使用的是舊版 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

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

設定錯誤

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

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

自訂效能評定

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

擷取指標

指標是指擷取效能評定資訊的主要類型資訊。可用選項包括 StartupTimingMetricFrameTimingMetricTraceSectionMetric。如要進一步瞭解相關資訊,請參閱擷取指標頁面。

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

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

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.FullCompilationMode.PartialCompilationMode.None

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

啟動模式

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

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

範例

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

提供意見

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