Skip to content

JUnitRunner

✅ Implemented 🧪 Tested

Current state: android/junit-runner/ is fully implemented. Includes @AutoMobileTest annotation, YAML plan execution via daemon socket, AI-assisted failure recovery, parallel multi-device execution, and historical timing-based test ordering. Published to Maven Central. See the Status Glossary for chip definitions.

The AutoMobile JUnitRunner lets you write host-side JVM tests that drive a real Android device or emulator over ADB. Tests execute as ordinary JUnit4 unit tests (src/test/), so they run in the standard testDebugUnitTest Gradle task with no instrumented build required.

How it works

sequenceDiagram
    participant G as Gradle testDebugUnitTest
    participant R as AutoMobileRunner (JVM)
    participant D as AutoMobile Daemon
    participant A as Android Device (ADB)

    G->>R: run test class
    R->>D: connect via Unix socket
    R->>D: executePlan(base64 YAML)
    D->>A: launchApp / observe / tapOn / …
    A-->>D: UI state + screenshots
    D-->>R: success / failedStep
    R-->>G: PASS or FAIL

Each test method references a YAML plan file in src/test/resources/. The runner encodes the plan content and sends it to the AutoMobile daemon over a Unix domain socket. The daemon drives the device step by step and returns a structured result. No special test APK is compiled; the device interaction happens entirely through the daemon.

Why not Espresso or UI Automator?

AutoMobile JUnitRunner Espresso / UI Automator
Runs as JVM unit test Instrumented APK on device
Build time No test APK compile Full assembleAndroidTest pass
Device needed at Test execution Build time (lint) + execution
Parallel devices Daemon-managed pool One device per Gradle worker
AI recovery Optional self-healing Not available
Test authoring YAML plans or AI prompt Kotlin/Java code

Requirements

  • JDK 11+
  • Android SDK with adb on PATH
  • A connected Android device or running emulator
  • AutoMobile daemon running (npm install -g @kaeawc/auto-mobile --ignore-scripts then auto-mobile --daemon-mode)
  • CtrlProxy accessibility service installed on the device (see CtrlProxy)

Quick start

1. Add the dependency

# gradle/libs.versions.toml
[versions]
auto-mobile-junit-runner = "0.0.13"

[libraries]
auto-mobile-junit-runner = { module = "dev.jasonpearson.auto-mobile:auto-mobile-junit-runner", version.ref = "auto-mobile-junit-runner" }

// app/build.gradle.kts
dependencies {
    testImplementation(libs.auto.mobile.junit.runner)
}

// app/build.gradle.kts
dependencies {
    testImplementation("dev.jasonpearson.auto-mobile:auto-mobile-junit-runner:0.0.13")
}

2. Write a test

// app/src/test/java/com/example/AppLaunchTest.kt
package com.example

import dev.jasonpearson.automobile.junit.AutoMobileRunner
import dev.jasonpearson.automobile.junit.AutoMobileTest
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AutoMobileRunner::class)
class AppLaunchTest {

    @Test
    @AutoMobileTest(
        plan = "test-plans/launch-app.yaml",
        appId = "com.example.app",
        aiAssistance = false,
        timeoutMs = 60_000L,
    )
    fun `app launches without crashing`() {
        // AutoMobileRunner executes the YAML plan and fails the test if any step fails
    }
}

3. Write the plan

# app/src/test/resources/test-plans/launch-app.yaml
---
name: launch-app
description: Launch the app and verify it opens without crashing
steps:
  - tool: launchApp
    appId: com.example.app
    clearAppData: true
    label: Launch the app with a clean state

  - tool: observe
    label: Verify the app UI renders without crashing

  - tool: terminateApp
    appId: com.example.app
    label: Terminate the app after test

4. Run

# Ensure the app is installed on a running emulator first
./gradlew assembleDebug
adb install -r app/build/outputs/apk/debug/app-debug.apk

# Start the daemon (if not already running)
auto-mobile --daemon-mode &

# Run the AutoMobile tests
./gradlew :app:testDebugUnitTest --tests 'com.example.*'

See Project Setup → Running tests locally for the full step-by-step walkthrough including daemon verification and CtrlProxy pre-installation.

Pages in this section

Page What it covers
Project Setup Gradle config, version catalog, env vars, running locally
Writing Tests @AutoMobileTest parameters, YAML plan reference, examples
CI Integration GitHub Actions, emulator.wtf ADB session, CtrlProxy pre-install