AndroidBenchmarkRunner

open class AndroidBenchmarkRunner : AndroidJUnitRunner

kotlin.Any
   ↳ android.app.Instrumentation
     ↳ androidx.test.runner.MonitoringInstrumentation
       ↳ androidx.test.runner.AndroidJUnitRunner
         ↳ androidx.benchmark.junit4.AndroidBenchmarkRunner

Instrumentation runner for benchmarks, used to increase stability of measurements and minimize interference.

To use this runner, put the following in your module level build.gradle:

android {
    defaultConfig {
        testInstrumentationRunner "androidx.benchmark.junit4.AndroidBenchmarkRunner"
    }
}

Minimizing Interference

This runner launches a simple opaque activity used to reduce benchmark interference from other windows. Launching other activities is supported e.g. via ActivityTestRule and ActivityScenario - the opaque activity will be relaunched if not actively running before each test, and after each test's cleanup is complete.

For example, sources of potential interference:

  • live wallpaper rendering

  • homescreen widget updates

  • hotword detection

  • status bar repaints

  • running in background (some cores may be foreground-app only)

Clock Stability

While it is better for performance stability to lock clocks with the ./gradlew lockClocks task provided by the gradle plugin, this is not possible on most devices. The runner provides a fallback mode for preventing thermal throttling.

On devices that support android.view.Window.setSustainedPerformanceMode, the runner will set this mode on the window of every Activity launched (including the opaque Activity mentioned above). The runner will also launch a continuously spinning Thread. Together, these ensure that the app runs in the multithreaded stable performance mode, which locks the maximum clock frequency to prevent thermal throttling. This ensures stable clock levels across all benchmarks, even if a continuous suite of benchmarks runs for many minutes on end.

Summary

Public constructors

Public functions
open Unit

Protected functions
open Unit

Ensures we've onStopped() all activities which were onStarted().

Inherited functions
From androidx.test.runner.AndroidJUnitRunner
open Application
newApplication(cl: ClassLoader, className: String, context: Context)

Does initialization before creating the application.
open Unit
onCreate(arguments: Bundle)

Sets up lifecycle monitoring, and argument registry.
open Boolean
open Unit

This implementation of onStart() will guarantee that the Application's onCreate method has completed when it returns.
open Unit
sendStatus(resultCode: Int, results: Bundle)
From android.app.Instrumentation
open TestLooperManager
open Unit
open Instrumentation.ActivityMonitor
addMonitor(
    cls: String,
    result: Instrumentation.ActivityResult,
    block: Boolean
)
open Instrumentation.ActivityMonitor
addMonitor(
    filter: IntentFilter,
    result: Instrumentation.ActivityResult,
    block: Boolean
)
open Unit
addResults(results: Bundle)
open Unit
callActivityOnCreate(
    activity: Activity,
    icicle: Bundle,
    persistentState: PersistableBundle
)
open Unit
callActivityOnNewIntent(activity: Activity, intent: Intent)
open Unit
open Unit
callActivityOnPostCreate(activity: Activity, savedInstanceState: Bundle?)
open Unit
callActivityOnPostCreate(
    activity: Activity,
    savedInstanceState: Bundle?,
    persistentState: PersistableBundle?
)
open Unit
callActivityOnRestoreInstanceState(
    activity: Activity,
    savedInstanceState: Bundle
)
open Unit
callActivityOnRestoreInstanceState(
    activity: Activity,
    savedInstanceState: Bundle?,
    persistentState: PersistableBundle?
)
open Unit
open Unit
callActivityOnSaveInstanceState(
    activity: Activity,
    outState: Bundle,
    outPersistentState: PersistableBundle
)
open Unit
open Boolean
open Unit
open Bundle
open Bundle
open ComponentName
open Context
open String
open Context
open UiAutomation
open UiAutomation
open Boolean
invokeContextMenuAction(targetActivity: Activity, id: Int, flag: Int)
open Boolean
invokeMenuActionSync(targetActivity: Activity, id: Int, flag: Int)
open Boolean
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Activity
startActivitySync(intent: Intent, options: Bundle?)
open Unit

This function is deprecated.
open Unit
open Unit
open Unit

This function is deprecated.
open Unit
open Unit
waitForIdle(recipient: Runnable)
open Unit
open Activity
open Activity
From androidx.test.runner.MonitoringInstrumentation
open Unit
callActivityOnCreate(activity: Activity, bundle: Bundle)
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
open Unit
execStartActivities(
    who: Context,
    contextThread: IBinder,
    token: IBinder,
    target: Activity,
    intents: Array<Intent>,
    options: Bundle
)
open Instrumentation.ActivityResult
execStartActivity(
    who: Context,
    contextThread: IBinder,
    token: IBinder,
    target: Activity,
    intent: Intent,
    requestCode: Int
)
open Instrumentation.ActivityResult
execStartActivity(
    who: Context,
    contextThread: IBinder,
    token: IBinder,
    target: Activity,
    intent: Intent,
    requestCode: Int,
    options: Bundle
)
open Instrumentation.ActivityResult
execStartActivity(
    who: Context,
    contextThread: IBinder,
    token: IBinder,
    target: Fragment,
    intent: Intent,
    requestCode: Int,
    options: Bundle
)
open Instrumentation.ActivityResult
execStartActivity(
    who: Context,
    contextThread: IBinder,
    token: IBinder,
    target: String,
    intent: Intent,
    requestCode: Int,
    options: Bundle
)

This API was added in Android API 23 (M)
open Instrumentation.ActivityResult
execStartActivity(
    who: Context,
    contextThread: IBinder,
    token: IBinder,
    target: Activity,
    intent: Intent,
    requestCode: Int,
    options: Bundle,
    user: UserHandle
)

This API was added in Android API 17 (JELLY_BEAN_MR1)
open Unit
finish(resultCode: Int, results: Bundle)
open String
open Unit
open Unit
installOldMultiDex(multidexClass: Class<*>)

Perform application MultiDex installation only when instrumentation installation is not available.
open Unit
interceptActivityUsing(
    interceptingActivityFactory: InterceptingActivityFactory
)

Use the given InterceptingActivityFactory to create Activity instance in newActivity.
Boolean

Checks whether this instance of instrumentation should be considered as a primary instrumentation process.
open Boolean
isPrimaryInstrProcess(argsProcessName: String?)

This function is deprecated.

use isPrimaryInstrProcess()
open Activity
newActivity(cl: ClassLoader, className: String, intent: Intent)
open Activity
newActivity(
    clazz: Class<*>,
    context: Context,
    token: IBinder,
    application: Application,
    intent: Intent,
    info: ActivityInfo,
    title: CharSequence,
    parent: Activity,
    id: String,
    lastNonConfigurationInstance: Any
)
open Unit
open Unit
Unit
open Boolean
open Unit
open Activity
open Throwable

Unwraps an exception from certain wrapper types, e.g. RuntimeException.
open Unit

Use default mechanism of creating activity instance in newActivity

Public constructors

AndroidBenchmarkRunner

Added in 1.0.0
AndroidBenchmarkRunner()

Public functions

onDestroy

@CallSuper
open fun onDestroy(): Unit

Protected functions

waitForActivitiesToComplete

@CallSuper
protected open fun waitForActivitiesToComplete(): Unit

Ensures we've onStopped() all activities which were onStarted().

According to Activity's contract, the process is not killable between onStart and onStop. Breaking this contract (which finish() will if you let it) can cause bad behaviour (including a full restart of system_server).

We give the app 2 seconds to stop all its activities, then we proceed.

This should never be run on the main thread.