Control Your App From Macrobenchmark

Unlike most Android UI tests, the Macrobenchmark tests run in a separate process from the app itself. This is necessary to enable things like stopping the app process and compiling from DEX bytecode to machine code.

You can drive your app's state using the UIAutomator library or other mechanisms that can control the target application from the test process. Approaches such as Espresso or ActivityScenario won't work for Macrobenchmark because they expect to run in a shared process with the app.

The following example finds a RecyclerView using its resource id, and scrolls down several times:

@Test
fun scrollList() {
    benchmarkRule.measureRepeated(
        // ...
        setupBlock = {
            // Before starting to measure, navigate to the UI to be measured
            val intent = Intent("$packageName.RECYCLER_VIEW_ACTIVITY")
            startActivityAndWait(intent)
        }
    ) {
        val recycler = device.findObject(By.res(packageName, "recycler"))
        // Set gesture margin to avoid triggering gesture navigation
        // with input events from automation.
        recycler.setGestureMargin(device.displayWidth / 5)

        // Scroll down several times
        repeat(3) { recycler.fling(Direction.DOWN) }
    }
}
FrameTimingBenchmark.kt

@Test
public void scrollList() {
    benchmarkRule.measureRepeated(
        // ...
        /* setupBlock */ scope -> {
            // Before starting to measure, navigate to the UI to be measured
            val intent = Intent("$packageName.RECYCLER_VIEW_ACTIVITY")
            scope.startActivityAndWait();
            return Unit.INSTANCE;
        },
        /* measureBlock */ scope -> {
            UiDevice device = scope.getDevice();
            UiObject2 recycler = device.findObject(By.res(scope.getPackageName(), "recycler"));

            // Set gesture margin to avoid triggering gesture navigation
            // with input events from automation.
            recycler.setGestureMargin(device.getDisplayWidth() / 5);

            // Fling the recycler several times
            for (int i = 0; i < 3; i++) {
                recycler.fling(Direction.DOWN);
            }

            return Unit.INSTANCE;
        }
    );
}

Your benchmark doesn't have to scroll the UI. It could instead, for example, run an animation. It also doesn't need to use UI Automator specifically; as long as frames are being produced by the view system, which includes frames produced by Jetpack Compose, performance metrics are collected.

Navigate to internal parts of the app

Sometimes you want to benchmark parts of your app which are not directly accessible from outside. This may be for example accessing inner Activities (marked with exported=false), navigating to a Fragment, or swiping some part of your UI away. The benchmarks need to navigate to those parts of the app “manually” as a user would.

This can be done by changing the code inside setupBlock{} to contain the desired effect (button click, swipe, etc.). Your measureBlock{} contains only the UI manipulation you want to actually benchmark.

@Test
fun nonExportedActivityScrollList() {
    benchmarkRule.measureRepeated(
        // ...
        setupBlock = setupBenchmark()
    ) {
        // ...
    }
}

private fun setupBenchmark(): MacrobenchmarkScope.() -> Unit = {
    // Before starting to measure, navigate to the UI to be measured
    startActivityAndWait()

    // click a button to launch the target activity.
    // While we use resourceId here to find the button, you could also use
    // accessibility info or button text content.
    val selector = By.res(packageName, "launchRecyclerActivity")
    if (!device.wait(Until.hasObject(selector), 5_500)) {
        fail("Could not find resource in time")
    }
    val launchRecyclerActivity = device.findObject(selector)
    launchRecyclerActivity.click()

    // wait until the activity is shown
    device.wait(
        Until.hasObject(By.clazz("$packageName.NonExportedRecyclerActivity")),
        TimeUnit.SECONDS.toMillis(10)
    )
}
NonExportedActivityBenchmark.kt

@Test
public void scrollList() {
    benchmarkRule.measureRepeated(
        // ...
        /* setupBlock */ scope -> {
            // Before starting to measure, navigate to the default activity
            scope.startActivityAndWait();

            // click a button to launch the target activity.
            // While we use resourceId here to find the button, you could also use
            // accessibility info or button text content.
            UiObject2 launchRecyclerActivity = scope.getDevice().findObject(
                By.res(packageName, "launchRecyclerActivity")
            )
            launchRecyclerActivity.click();

            // wait until activity is shown
            scope.getDevice().wait(
                Until.hasObject(By.clazz("$packageName.NonExportedRecyclerActivity")),
                10000L
            )

            return Unit.INSTANCE;
        },
        /* measureBlock */ scope -> {
            // ...
        }
    );
}