android-macrobenchmark

name	android-macrobenchmark
description	Use when evaluating App Startup Time, frame timing, and writing Baseline Profiles.
category	performance
risk	medium
source	community
date_added	2026-04-07
metadata	{"triggers":["@macrobenchmark","baseline profile","app startup time"]}

Android Macrobenchmark & Baseline Profiles 🏎️

App Startup Time and UI performance are crucial. Macrobenchmark allows us to write standard JUnit 4 tests to measure end-to-end user journeys (like app startup or scrolling a list) and automatically generate Baseline Profiles that Android's ART uses to pre-compile critical code.

⚡ When to Use

• When the prompt mentions "speeding up app startup time"
• When writing a Macrobenchmark module
• When generating or applying Baseline Profiles (baseline-prof.txt)

🏗️ Core Rules / Pillars

1. Separate Macrobenchmark Module

• Pattern: Macrobenchmarks MUST be in a separate com.android.test module. They launch your application by its applicationId externally.
• Anti-Pattern: Do NOT attempt to run Macrobenchmark tests inside the standard app/src/androidTest directory.

2. Writing a Scrolling Benchmark

• Implementation:

  @RunWith(AndroidJUnit4::class)
  class ScrollBenchmark {
      @get:Rule
      val benchmarkRule = MacrobenchmarkRule()
  
      @Test
      fun scrollTimeline() = benchmarkRule.measureRepeated(
          packageName = "com.example.app",
          metrics = listOf(FrameTimingMetric()),
          iterations = 5,
          startupMode = StartupMode.COLD
      ) {
          pressHome()
          startActivityAndWait()
          
          // Using UIAutomator to find the scrollable list and scroll
          val list = device.findObject(By.res("com.example.app", "timeline_list"))
          list.setGestureMargin(device.displayWidth / 5)
          list.fling(Direction.DOWN)
      }
  }
  

🚧 Critical Anti-Hallucination Guards

• Trap: Baseline Profiles generation requires a rooted device OR a device running Android 13 (API 33)+.

🔗 Related Resources

• Macrobenchmark Documentation