A GitHub Action for installing, configuring and running hardware-accelerated Android Emulators on macOS virtual machines (or Linux virtual machines but without hardware accleration).

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 and system-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.

It is recommended to run this action on a macOS VM, e.g. macos-latest or macos-10.15 to take advantage of hardware accleration support provided by HAXM.

Please note that while Linux VMs (e.g. ubuntu-latest or ubuntu-18.04) are also supported, hardware acceleration will not be available.

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

If you need specific versions of NDK and CMake installed:

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
        ndk: 21.0.6113669
        cmake: 3.10.2.4988404
        script: ./gradlew connectedCheck

Default emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim.

Please note that if you are running on a Linux VM, -no-accel will be added to the emulator-options to make sure hardware acceleration is turned off.

These are some of the open-source projects using (or used) Android Emulator Runner:

• coil-kt/coil
• cashapp/sqldelight
• square/workflow
• square/retrofit
• natario1/CameraView
• natario1/Transcoder
• chrisbanes/insetter
• slackhq/keeper
• android/compose-samples
• ReactiveCircus/streamlined
• ReactiveCircus/FlowBinding
• vinaygaba/Learn-Jetpack-Compose-By-Example
• ashishb/adb-enhanced

If you are using Android Emulator Runner and want your project included in the list, please feel free to create an issue or open a pull request.