A GitHub Action for installing, configuring and running Android Emulators on macOS virtual machines.
The old ARM-based emulators were slow and are no longer supported by Google. The modern Intel Atom (x86 and x86_64) emulators require hardware acceleration (HAXM on Mac & Windows, QEMU on Linux) from the host to run fast. This presents a challenge on CI as to be able to run hardware accelerated emulators within a docker container, KVM must be supported by the host VM which isn't the case for cloud-based CI providers due to infrastructural limits. If you want to learn more about this, here's an article I wrote: Running Android Instrumented Tests on CI.
The masOS VM provided by GitHub Actions has HAXM installed so we are able to create a new AVD instance, launch an emulator with hardware acceleration, and run our Android tests directly on the VM.
This action automates the process by doing the following:
- Install / update the required Android SDK components including
build-tools
,platform-tools
,platform
(for the required API level),emulator
andsystem-images
(for the required API level). - Create a new instance of AVD with the provided configurations.
- Launch a new Emulator with the provided configurations.
- Wait until the Emulator is booted and ready for use.
- Run a custom script provided by user once the Emulator is up and running - e.g.
./gradlew connectedCheck
. - Kill the Emulator and finish the action.
Note that this action must be run on a macOS VM, e.g. macOS-latest
or macOS-10.14
.
A workflow that uses android-emulator-runner to run your instrumented tests on API 29:
jobs:
test:
runs-on: macOS-latest
steps:
- name: checkout
uses: actions/checkout@v2
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 29
script: ./gradlew connectedCheck
We can also leverage GitHub Actions's build matrix to test across multiple configurations:
jobs:
test:
runs-on: macOS-latest
strategy:
matrix:
api-level: [21, 23, 29]
target: [default, google_apis]
steps:
- name: checkout
uses: actions/checkout@v2
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: ${{ matrix.api-level }}
target: ${{ matrix.target }}
arch: x86_64
profile: Nexus 6
script: ./gradlew connectedCheck
Required | Default | Description | |
---|---|---|---|
api-level |
Required | N/A | API level of the platform system image - e.g. 23 for Android Marshmallow, 29 for Android 10. Minimum API level supported is 15. |
target |
Optional | default |
Target of the system image - default or google_apis . |
arch |
Optional | x86 |
CPU architecture of the system image - x86 or x86_64 . Note that x86_64 image is only available for API 21+. |
profile |
Optional | N/A | Hardware profile used for creating the AVD - e.g. Nexus 6 . For a list of all profiles available, run $ANDROID_HOME/tools/bin/avdmanager list and refer to the results under "Available Android Virtual Devices". |
emulator-options |
Optional | See below | Command-line options used when launching the emulator (replacing all default options) - e.g. -no-window -no-snapshot -camera-back emulated . |
disable-animations |
Optional | true |
Whether to disable animations - true or false . |
emulator-build |
Optional | N/A | Build number of a specific version of the emulator binary to use e.g. 6061023 for emulator v29.3.0.0. |
working-directory |
Optional | ./ |
A custom working directory - e.g. ./android if your root Gradle project is under the ./android sub-directory within your repository. |
script |
Required | N/A | Custom script to run - e.g. to run Android instrumented tests on the emulator: ./gradlew connectedCheck |
Default emulator-options
: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim
.