Android Emulator Plugin

This plugin adds tasks that install an Android emulator and start it up when running instrumentation tests. Includes configuration for specifying the emulator configuration.

This plugin will automatically accept all Android SDK licenses when installing the emulator and emulator system images. Before using the plugin or upgrading Android SDK versions, make sure you are okay accepting the licenses for those versions.

Consumption

The minimum requirement for consumption is to simply apply this plugin.

build.gradle

// Consume from Gradle plugin repository. This is the only required step.
plugins {
    id 'com.quittle.android-emulator' version 'X.X.X'
}

// Consume android plugin as usual.
apply plugin: 'android'

android {
    // Fill out normally
}

// Optional configuration
androidEmulator {
    emulator {
        name 'my_avd_emulator_name' // Defaults to be dynamically based on the configuration of the AVD
        device 'pixel_xl' // Defaults to exclude the device flag, using avdmanager default. For options, run avdmanager list device
        sdkVersion 28 // Defaults to (Target SDK), then (Min SDK), then finally 10
        abi 'x86_64' // Defaults to x86
        includeGoogleApis true // Defaults to false
    }

    enableForAndroidTests false // Defaults to true
    avdRoot '~/.android/avd' // Defaults to be <gradle-build-dir>/android-avd-root
    headless true // Defaults to false but should be set to true for most CI systems
    additionalSdkManagerArguments '--proxy=http', '--proxy_host=56.78.90.12', '--proxy_port=1234' // Additional arguments to pass to the sdkmanager when used to install dependencies. See https://developer.android.com/studio/command-line/sdkmanager#options for options
    additionalEmulatorArguments '-no-snapshot', '-http-proxy=localhost:1234' // Additional arguments to pass to the emulator at startup. See https://developer.android.com/studio/run/emulator-commandline#startup-options for options
    logEmulatorOutput true // Defaults to false but can be enabled to have emulator output logged for debugging.
}

Tips & Tricks

Emulator failing to start

If the emulator fails to start with an error like

Emulator exited abnormally with return code 1

and you are unsure what the cause is, set androidEmulator { logEmulatorOutput true } and re-run the gradle build or even just building the waitForAndroidEmulator with the --debug flag should do the trick. You should now see the emulator stdout and stderr being logged with error messages if there was a bad combination of startup flags.

Custom test task

If you have a reason to run a custom instrumentation test task rather than the default one generated by the Android Gradle plugin, you can certainly do so. All you must do to ensure the emulator is spun up and down at the appropriate times is

1. Configure your task to depend on waitForAndroidEmulator
2. Configure your task to be finalized by stopAndroidEmulator

Development

In general, perform builds in the context of each folder, rather than as a multi-project Gradle build. This is necessary because the example-android-project will fail to configure without the plugin being locally available so the android-emulator-plugin project must be built and deployed locally first.

In general, to build and test locally do the following

$ ./gradlew -p android-emulator-plugin # This runs all the default tasks
$ ./gradlew -p android-emulator-plugin publishToMavenLocal # Publishes it for the example-android-project to consume
$ ./validate_plugin # Integration test to validate the plugin works

Deployment

This package is deployed via CircleCI. See .circleci/config.yml for the CI/CD setup.

In the configuration for the project on CircleCI, GRADLE_PUBLISH_KEY and GRADLE_PUBLISH_SECRET are injected as environment variables.

Upon check-in to the main branch, CircleCI checks out and builds the plugin. When a commit is tagged, a new version of the plugin will be released using the tag version number.