Open-Source Testing · ReactiveCircus

android-emulator-runner

android-emulator-runner is a GitHub Action that automates Android emulator setup and hardware-accelerated execution for CI/CD pipelines on Linux and macOS. It handles SDK installation, AVD creation, emulator launch, and test execution without manual intervention.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/ReactiveCircus/android-emulator-runner

1.3k

GitHub stars

252

Forks

TypeScript

Primary language

Apache-2.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	ReactiveCircus/android-emulator-runner
Owner	ReactiveCircus
Primary language	TypeScript
License	Apache-2.0 — OSI-approved
Stars	1.3k
Forks	252
Open issues	90
Latest release	v2.38.0 (2026-07-05)
Last updated	2026-07-05
Source	https://github.com/ReactiveCircus/android-emulator-runner

What android-emulator-runner is

TypeScript-based GitHub Action that orchestrates Android SDK component provisioning, AVD instantiation with configurable profiles/API levels, and hardware-accelerated emulator execution leveraging KVM (Linux) or Hypervisor.Framework (macOS). Supports NDK/CMake pinning, snapshot caching, and custom test scripts.

Quickstart

Get the android-emulator-runner source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/ReactiveCircus/android-emulator-runner.git2cd android-emulator-runner3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Android CI/CD Testing at Scale

Run instrumented tests across multiple API levels and device profiles in parallel using GitHub Actions build matrix, with hardware acceleration for 2-3x faster execution compared to ARM emulators.

Emulator Snapshot Caching Workflows

Leverage AVD snapshot caching with GitHub Actions cache to reduce repeated emulator startup times, critical for high-frequency test runs in large monorepos or multi-variant builds.

Gradle Plugin & SDK Tool Testing

Test Android build tools, Gradle plugins, and SDK Extensions across target API levels with reproducible emulator configurations without local developer machine overhead.

Implementation considerations

Explicitly enable KVM group permissions on Linux runners via udev rules before invoking the action; macOS uses native Hypervisor.Framework and does not require manual HAXM installation.
Configure AVD snapshot caching with actions/cache@v5 and gradle/actions/setup-gradle to reduce startup overhead; requires careful ordering of workflow steps and cache-hit conditional logic.
Pin NDK and CMake versions if required; action downloads components on-demand; verify compatibility with your target API level and build system to avoid silent version mismatches.
Test emulator-options flags (e.g., -gpu swiftshader_indirect, -no-window, -no-boot-anim) to balance performance vs. observability; some flags incompatible with certain architectures or targets.
Plan for longer CI job runtimes on first run; emulator startup + SDK provisioning can exceed 5-10 minutes; design timeouts and retry logic accordingly.

When to avoid it — and what to weigh

Non-GitHub CI Systems — This is a GitHub Action; use alternative tooling (Fastlane, Gradle plugin, or native CI integrations) if your CI provider is Jenkins, GitLab CI, CircleCI, or others.
GUI/Visual Testing as Primary Goal — While GPU acceleration is supported, this action is optimized for headless instrumented testing; for visual/screenshot regression testing, consider dedicated UI testing platforms.
Nested Virtualization Unavailable — Requires host VM support for hardware acceleration (KVM on Linux, Hypervisor.Framework on macOS); will not work efficiently on constrained Docker/cloud environments without nested virtualization.
Windows Runners — Action officially supports Linux (ubuntu-latest with KVM) and macOS; Windows support is not documented and likely not functional for hardware acceleration.

License & commercial use

Apache License 2.0 (Apache-2.0). Permissive OSI-approved license allowing commercial use, distribution, and modification with attribution and liability disclaimers. Source code available under this license; no proprietary restrictions.

Apache-2.0 is a permissive OSI license that explicitly permits commercial use in CI/CD workflows. No license fees or proprietary restrictions apply. Safe for enterprise adoption as-is. Verify with internal legal teams if packaging or redistributing the action code in proprietary products.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Strong
Assessment confidence	High

Security considerations

GitHub Actions runners are ephemeral and isolated; emulator runs in sandbox context. Considerations: (1) SDK downloads from Google's repositories—verify network integrity; (2) custom scripts (./gradlew connectedCheck) execute with runner privileges; audit script content for credential leaks; (3) cache may store sensitive AVD state—GitHub Actions cache is encrypted at rest but accessible to all workflows in the repo; (4) no documented supply-chain verification for Android SDK components; (5) KVM group configuration on Linux grants broad device access—follow principle of least privilege.

Alternatives to consider

Android Gradle Plugin emulator tests (local)

Native Gradle task integration; no external CI dependency. Slower without hardware acceleration; requires developer machines with KVM/virtualization support; not suitable for headless CI.

Fastlane (scan, setup_ci)

Cross-platform CI/CD orchestration supporting multiple emulator providers. More verbose; not GitHub Actions-native; steeper learning curve; broader scope beyond testing.

Browserstack / AWS Device Farm / Firebase Test Lab

Cloud-hosted Android device/emulator labs with no on-premises virtualization setup. Higher per-minute costs; external vendor dependency; reduced control over environment reproducibility.

Software development agency

Build on android-emulator-runner with DEV.co software developers

Integrate android-emulator-runner into your GitHub Actions workflows to run hardware-accelerated emulator tests 2-3x faster. Start with the quick-start example in the README.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

marathon httprunner test-butler

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Android App Development CI/CD Pipeline Setup API & Backend Testing Talk to DEV.co

android-emulator-runner FAQ

Do I need to install HAXM on macOS?

No. macOS 10.10+ uses the native Hypervisor.Framework by default. HAXM is a kernel extension and redundant; manual installation can cause popup dialogs and is not recommended per the README.

Can I use this action on Windows or standard macOS runners without KVM?

Windows is not documented as supported. macOS runners rely on Hypervisor.Framework (available by default) and do not require KVM. Linux runners require explicit KVM enablement via udev rules; standard ubuntu-latest runners support hardware acceleration.

How do I speed up repeated test runs?

Use actions/cache@v5 to cache ~/.android/avd/* and ~/.android/adb* with a key based on api-level and target. Run the action twice: once to generate a snapshot (without -no-snapshot-save), then again to reuse it (with -no-snapshot-save). Requires careful step ordering and cache-hit conditionals.

What happens if the emulator fails to boot?

The action waits for emulator boot readiness; if boot times out or fails, the action will error and stop. Provide clear error logs from the runner logs. Common causes: insufficient disk space, incompatible architecture/API level combinations, malformed emulator-options, or KVM misconfiguration on Linux.

Work with a software development agency

DEV.co helps companies turn open-source tools like android-emulator-runner into production software. Our software development services cover the full lifecycle — architecture, web development, integration, and maintenance — delivered by software developers and web developers who ship. Engage our software development agency to implement or customize it for your open-source testing stack.

Ready to accelerate Android CI/CD testing?

Integrate android-emulator-runner into your GitHub Actions workflows to run hardware-accelerated emulator tests 2-3x faster. Start with the quick-start example in the README.

Talk to DEV.co Schedule a Consultation