Main changes of the fork repo: Support to remain the running of emulator after the action is completed. This is enabled by using the auto-kill-emulator parameter and setting it to false.
A GitHub Action for installing, configuring and running hardware-accelerated Android Emulators on Linux and 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 can be fast, but rely on two forms of hardware acceleration to reach their peak potential: Graphics Acceleration, e.g. emulator -gpu host and Virtual Machine(VM) Acceleration, e.g. emulator -accel on. Note: GPU and VM Acceleration are two different and non-mutually exclusive forms of Hardware Acceleration.
This presents a challenge when running emulators on CI especially when running emulators within a docker container, because Nested Virtualization must be supported by the host VM which isn't the case for most cloud-based CI providers due to infrastructural limits. If you want to learn more about Emulators on CI, here's an article Yang wrote: Running Android Instrumented Tests on CI.
GitHub's larger Linux runners support running hardware accelerated emulators which is free for public GitHub repos. It is now recommended to use the Ubuntu (ubuntu-latest) runners which are 2-3 times faster than the macOS ones which are also a lot more expensive. Remember to enable KVM in your workflow before running this action:
- name: Enable KVM group perms
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
According to this documentation, "on Mac OS X v10.10 Yosemite and higher, the Android Emulator uses the built-in Hypervisor.Framework by default, and falls back to using Intel HAXM if Hypervisor.Framework fails to initialize." This means that HAXM is only needed to achieve VM Acceleration if this default Hypervisor is not available on macOS machines.
Note: Manually enabling and downloading HAXM is not recommended because it is redundant and not needed (see above), and for users of macOS 10.13 High Sierra and higher: macOS 10.13 disables installation of kernel extensions by default. Because Intel HAXM is a kernel extension, we would need to manually enable its installation on the base runner VM. Furthermore, manually trying to install HAXM on a Github Runner brings up a popup which further hinders tests from running.
This action helps automate and configure the process of setting up an emulator and running your tests by doing the following:
- Install / update the required Android SDK components including
build-tools,platform-tools,platform(for the required API level),emulatorandsystem-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.
A workflow that uses android-emulator-runner to run your instrumented tests on API 29:
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v4
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 29
script: ./gradlew connectedCheckWe can also leverage GitHub Actions's build matrix to test across multiple configurations:
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
api-level: [21, 23, 29]
target: [default, google_apis]
steps:
- name: checkout
uses: actions/checkout@v4
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- 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 connectedCheckIf you need specific versions of NDK and CMake installed:
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v4
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 29
ndk: 21.0.6113669
cmake: 3.10.2.4988404
script: ./gradlew connectedCheckIf you need a specific SDK Extensions for the system image but not the platform:
jobs:
test:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/checkout@v4
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 34
system-image-api-level: 34-ext9
target: android-automotive
script: ./gradlew connectedCheckWe can significantly reduce emulator startup time by setting up AVD snapshot caching:
- add a
gradle/actions/setup-gradle@v4step for caching Gradle, more details see #229 - add an
actions/cache@v4step for caching theavd - add a
reactivecircus/android-emulator-runner@v2step to generate a clean snapshot - specifyemulator-optionswithoutno-snapshot - add another
reactivecircus/android-emulator-runner@v2step to run your tests using existing AVD / snapshot - specifyemulator-optionswithno-snapshot-save
jobs:
test:
runs-on: ubuntu-latest
strategy:
matrix:
api-level: [21, 23, 29]
steps:
- name: checkout
uses: actions/checkout@v4
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
sudo udevadm control --reload-rules
sudo udevadm trigger --name-match=kvm
- name: Gradle cache
uses: gradle/actions/setup-gradle@v3
- name: AVD cache
uses: actions/cache@v4
id: avd-cache
with:
path: |
~/.android/avd/*
~/.android/adb*
key: avd-${{ matrix.api-level }}
- name: create AVD and generate snapshot for caching
if: steps.avd-cache.outputs.cache-hit != 'true'
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: ${{ matrix.api-level }}
force-avd-creation: false
emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
disable-animations: false
script: echo "Generated AVD snapshot for caching."
- name: run tests
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: ${{ matrix.api-level }}
force-avd-creation: false
emulator-options: -no-snapshot-save -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
disable-animations: true
script: ./gradlew connectedCheckDefault emulator-options: -no-window -gpu swiftshader_indirect -no-snapshot -noaudio -no-boot-anim.
These are some of the open-source projects using (or used) Android Emulator Runner:
- coil-kt/coil
- cashapp/sqldelight
- square/workflow-kotlin
- square/retrofit
- natario1/CameraView
- natario1/Transcoder
- chrisbanes/insetter
- slackhq/keeper
- android/compose-samples
- ReactiveCircus/streamlined
- ReactiveCircus/FlowBinding
- JakeWharton/RxBinding
- vinaygaba/Learn-Jetpack-Compose-By-Example
- ashishb/adb-enhanced
- vgaidarji/ci-matters
- simpledotorg/simple-android
- cashapp/copper
- square/radiography
- Shopify/android-testify
- square/leakcanary
- hash-checker/hash-checker
- hash-checker/hash-checker-lite
- Kiwix/kiwix-android
- wikimedia/apps-android-wikipedia
- google/android-fhir
- google/accompanist
- dotanuki-labs/norris
- tinylog-org/tinylog
- hzi-braunschweig/SORMAS-Project
- ACRA/acra
- bitfireAT/davx5-ose
- robolectric/robolectric
- home-assistant/android
If you are using Android Emulator Runner and want your project included in the list, please feel free to open a pull request.