Напишите макробенчмарк

Библиотека Macrobenchmark используется для тестирования более сложных сценариев использования вашего приложения, включая запуск приложения и сложные манипуляции с пользовательским интерфейсом, такие как прокрутка RecyclerView или запуск анимаций. Если вы хотите протестировать более мелкие участки кода, обратитесь к библиотеке Macrobenchmark . На этой странице показано, как настроить библиотеку Macrobenchmark.

Библиотека выводит результаты бенчмаркинга как в консоль Android Studio, так и в JSON-файл с более подробной информацией. Она также предоставляет файлы трассировки, которые можно загрузить и проанализировать в Android Studio.

Используйте библиотеку Macrobenchmark в среде непрерывной интеграции (CI), как описано в разделе «Бенчмаркинг в непрерывной интеграции» .

Для создания базовых профилей можно использовать Macrobenchmark. Сначала настройте библиотеку Macrobenchmark, а затем создайте базовый профиль .

Настройка проекта

Мы рекомендуем использовать Macrobenchmark с последней версией Android Studio для доступа к функциям IDE, интегрированным с Macrobenchmark.

Настройте модуль Macrobenchmark

Для работы макробенчмарков требуется модуль com.android.test — отдельный от кода вашего приложения — который отвечает за запуск тестов, измеряющих производительность вашего приложения.

В Android Studio доступен шаблон, упрощающий настройку модуля Macrobenchmark. Шаблон модуля бенчмаркинга автоматически создает в вашем проекте модуль для измерения производительности приложения, собранного с помощью этого модуля, включая пример теста производительности при запуске.

Чтобы использовать шаблон модуля для создания нового модуля, выполните следующие действия:

1. В Android Studio щелкните правой кнопкой мыши по своему проекту или модулю на панели «Проект» и выберите «Создать» > «Модуль» .

2. Выберите «Benchmark» на панели «Шаблоны» . Вы можете настроить целевое приложение — то есть приложение, которое будет тестироваться, — а также имя пакета и модуля для нового модуля Macrobenchmark.

3. Нажмите «Готово» .

Рисунок 1. Шаблон модуля бенчмарка.

Настройте приложение

Для проведения бенчмаркинга приложения — так называемого целевого объекта Macrobenchmark — приложение должно быть profileable , что позволяет считывать подробную информацию трассировки без ущерба для производительности. Мастер модулей автоматически добавляет тег <profileable> в файл AndroidManifest.xml приложения.

Убедитесь, что целевое приложение включает ProfilerInstaller версии 1.3 или выше, поскольку библиотека Macrobenchmark необходима для включения захвата и сброса профилей, а также очистки кэша шейдеров.

Настройте тестируемое приложение максимально близко к релизной или рабочей версии. Установите его как не отлаживаемое и желательно с включенной минификацией, что повышает производительность. Обычно это делается путем создания копии релизного варианта, который работает так же, но подписан локально отладочными ключами. В качестве альтернативы можно использовать initWith , чтобы указать Gradle сделать это за вас:

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

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

buildTypes {
    release {
        isMinifyEnabled = true
        isShrinkResources = true
        proguardFiles(
            getDefaultProguardFile("proguard-android-optimize.txt"),
            "keep-rules.pro"
        )
        // In real app, this would use its own release keystore
        signingConfig = signingConfigs.getByName("debug")
        baselineProfile.automaticGenerationDuringBuild = true
    }
}
build.gradle.kts

Чтобы гарантировать, что при запуске теста производительности будет собрана и протестирована правильная версия вашего приложения, как показано на рисунке 2, выполните следующие действия:

1. Выполните синхронизацию Gradle.
2. Откройте панель «Варианты сборки» .
3. Выберите вариант теста производительности как в самом приложении, так и в модуле Macrobenchmark.

Рисунок 2. Выберите эталонный вариант.

(Необязательно) Настройка многомодульного приложения

Если ваше приложение содержит более одного модуля Gradle, убедитесь, что ваши скрипты сборки знают, какой вариант сборки следует скомпилировать. Добавьте свойство matchingFallbacks в тип сборки benchmark для ваших модулей :macrobenchmark и :app . Остальные модули Gradle могут иметь ту же конфигурацию, что и раньше.

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

    matchingFallbacks += listOf("release")
 }

benchmark {
    initWith buildTypes.release
    signingConfig signingConfigs.debug

    matchingFallbacks = ['release']
 }

Без этого добавленный тип сборки benchmark приводит к сбою сборки и выдает следующее сообщение об ошибке:

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

При выборе вариантов сборки в вашем проекте выберите benchmark для модулей :app и :macrobenchmark , а release для любых других модулей вашего приложения, как показано на рисунке 3:

Рисунок 3. Варианты бенчмарка для многомодульного проекта с выбранными типами сборки: релизная и бенчмарк-версия.

Для получения дополнительной информации см. раздел «Использование управления зависимостями с учетом вариантов» .

(Необязательно) Настройка вкусов продукта

Если в вашем приложении задано несколько вариантов продукта, настройте модуль :macrobenchmark таким образом, чтобы он знал, какой вариант продукта вашего приложения следует собрать и протестировать.

В примерах на этой странице используются два варианта продукта из модуля :app : demo и production , как показано в следующем фрагменте кода:

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
        // ...
    }
    create("production") {
        dimension = "environment"
        // ...
    }
}

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
        // ...
    }

    production {
        dimension 'environment'
        // ...
    }
}

Без этой настройки вы можете получить ошибку сборки, аналогичную той, что возникает при использовании нескольких модулей Gradle:

Could not determine the dependencies of task ':macrobenchmark:connectedBenchmarkAndroidTest'.
> Could not determine the dependencies of null.
   > Could not resolve all task dependencies for configuration ':macrobenchmark:benchmarkTestedApks'.
      > Could not resolve project :app.
        Required by:
            project :macrobenchmark
         > The consumer was configured to find a runtime of a component, as well as attribute 'com.android.build.api.attributes.BuildTypeAttr' with value 'benchmark', attribute 'com.android.build.api.attributes.AgpVersionAttr' with value '7.3.0'. However we cannot choose between the following variants of project :app:
             -   demoBenchmarkRuntimeElements
             -   productionBenchmarkRuntimeElements
           All of them match the consumer attributes:
           ...

В двух следующих разделах описаны способы настройки бенчмаркинга с использованием нескольких вариантов продукта.

Используйте стратегию отсутствующих измерений

Указание missingDimensionStrategy в defaultConfig модуля :macrobenchmark сообщает системе сборки о необходимости использовать измерение, соответствующее типу сборки (flavor). Укажите, какие измерения использовать, если вы не нашли их в модуле. В следующем примере в качестве измерения по умолчанию используется production тип сборки (production):

defaultConfig {
    missingDimensionStrategy("environment", "production")
}

defaultConfig {
    missingDimensionStrategy "environment", "production"
}

Таким образом, модуль :macrobenchmark может собирать и тестировать только указанную версию продукта, что полезно, если известно, что только одна версия продукта имеет подходящую конфигурацию для тестирования.

Определите вкусы продуктов в модуле :macrobenchmark

Если вы хотите создать и протестировать другие варианты продукта, определите их в модуле :macrobenchmark . Укажите его аналогично модулю :app , но присвойте параметру productFlavors только dimension . Никаких других настроек не требуется:

flavorDimensions += "environment"
productFlavors {
    create("demo") {
        dimension = "environment"
    }
    create("production") {
        dimension = "environment"
    }
}

flavorDimensions 'environment'
productFlavors {
    demo {
        dimension 'environment'
    }

    production {
        dimension 'environment'
    }
}

После определения и синхронизации проекта выберите соответствующий вариант сборки на панели «Варианты сборки» , как показано на рисунке 4:

Рисунок 4. Варианты бенчмарка для проекта с указанием выбранных параметров продукта: "productionBenchmark" и "release".

Для получения дополнительной информации см. раздел «Устранение ошибок сборки, связанных с сопоставлением вариантов» .

Создайте класс для макротестирования производительности.

Тестирование производительности осуществляется через API правил JUnit4 MacrobenchmarkRule в библиотеке Macrobenchmark. Он содержит метод measureRepeated , позволяющий задавать различные условия запуска и тестирования целевого приложения.

Необходимо как минимум указать packageName целевого приложения, какие metrics вы хотите измерить и сколько iterations должен выполнить бенчмарк.

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

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

@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 , используя действие в боковой панели рядом с вашим тестовым классом или методом, как показано на рисунке 5.

Рисунок 5. Запустите Macrobenchmark с действием в боковой панели рядом с тестовым классом.

Также вы можете запустить все тесты производительности в модуле Gradle из командной строки, выполнив команду connectedCheck :

./gradlew :macrobenchmark:connectedCheck

Для запуска отдельного теста выполните следующую команду:

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

См. раздел «Бенчмаркинг в непрерывной интеграции» для получения информации о том, как запускать и отслеживать бенчмарки в непрерывной интеграции.

Результаты сравнительного анализа

После успешного выполнения теста производительности метрики отображаются непосредственно в Android Studio и выводятся для использования в CI в файле JSON . Каждая итерация измерения фиксирует отдельную трассировку системы. Вы можете открыть эти результаты трассировки, щелкнув по ссылкам на панели «Результаты теста» , как показано на рисунке 6:

Рисунок 6. Результаты запуска макротеста.

После загрузки трассировки Android Studio предложит вам выбрать процесс для анализа. В поле выбора предварительно будет указан процесс целевого приложения, как показано на рисунке 7:

Рисунок 7. Выбор процесса трассировки в студии.

После загрузки файла трассировки Studio отображает результаты в инструменте профилирования ЦП :

Рисунок 8. Трассировка в студии.

JSON-отчеты и любые трассировки профилирования также автоматически копируются с устройства на хост. На хост-машине они записываются в следующее местоположение:

project_root/module/build/outputs/connected_android_test_additional_output/debugAndroidTest/connected/device_id/

Получите доступ к файлам трассировки вручную.

Если вы хотите использовать инструмент Perfetto для анализа файла трассировки, потребуются дополнительные шаги. Perfetto позволяет проверять все процессы, происходящие на устройстве во время трассировки, в то время как профилировщик ЦП Android Studio ограничивает проверку одним процессом.

Если вы запускаете тесты из 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 .

Macrobenchmark также выдает ошибки при попытке измерения производительности эмулятора или на устройстве с низким зарядом батареи, что может поставить под угрозу доступность ядра и тактовую частоту.

Настройте параметры тестирования.

Функция measureRepeated принимает различные параметры, которые влияют на то, какие метрики будет собирать библиотека, как запускается и компилируется ваше приложение, а также сколько итераций будет выполняться тест производительности.

Собирайте метрики

Метрики — это основной тип информации, извлекаемой из ваших бенчмарков. Доступны следующие метрики:

• StartupTimingMetric
• FrameTimingMetric
• TraceSectionMetric

Для получения дополнительной информации о метриках см. раздел «Сбор метрик макробенчмарка» .

Улучшите данные трассировки с помощью пользовательских событий.

Может быть полезно добавить в ваше приложение пользовательские события трассировки, которые отображаются вместе с остальной частью отчета о трассировке и могут помочь выявить проблемы, специфичные для вашего приложения. Чтобы узнать больше о создании пользовательских событий трассировки, см. раздел «Определение пользовательских событий» .

Режим компиляции

В макротестах можно указать CompilationMode , который определяет, какая часть приложения должна быть предварительно скомпилирована из байт-кода DEX (формат байт-кода внутри APK) в машинный код (аналогично предварительно скомпилированному C++).

По умолчанию Macrobenchmarks запускаются с CompilationMode.DEFAULT , который устанавливает базовый профиль (если он доступен) на Android 7 (уровень API 24) и более поздних версиях. Если вы используете Android 6 (уровень API 23) или более ранние версии, режим компиляции полностью компилирует APK-файл в качестве стандартного системного поведения.

Вы можете установить базовый профиль, если целевое приложение содержит как базовый профиль, так и библиотеку ProfileInstaller .

В Android 7 и более поздних версиях можно настроить CompilationMode , чтобы повлиять на объем предварительной компиляции на устройстве имитировать различные уровни предварительной компиляции (AOT) или JIT-кэширования. См. CompilationMode.Full , CompilationMode.Partial , CompilationMode.None и CompilationMode.Ignore .

Эта функция основана на командах компиляции ART . Каждый тест очищает данные профилирования перед началом работы, чтобы предотвратить конфликты между тестами.

StartupMode

Для запуска активности можно указать предопределенный режим запуска: COLD , WARM или HOT . Этот параметр изменяет способ запуска активности и состояние процесса в начале теста.

Чтобы узнать больше о типах стартапов, см. раздел «Время запуска приложения» .

Образцы

Пример проекта доступен в репозитории Macrobenchmark Sample на GitHub.

Предоставьте отзыв

Чтобы сообщить о проблемах или отправить предложения по улучшению Jetpack Macrobenchmark, посетите общедоступный трекер проблем .