AI-powered UI test automation for Android, iOS, and React Native — author scenarios in natural language, let a Koog-powered LLM agent drive a real device or emulator.

---

Get Started

Prerequisites: JDK 21, Android Platform Tools (adb), Node 18+ for the dashboard, one LLM API key (DeepSeek, Gemini, Claude, OpenRouter, or local Ollama).

# 1. Configure environment
cp .env.example .env          # then fill in at least one LLM key + HOME_PATH

# 2. One-shot: backend (:8080) + dashboard (:5173) + open browser
./start.sh

# — or run them separately —
./gradlew run                                  # backend only
cd web && npm install && npm run dev           # dashboard only

Trigger a test scenario:

curl -X POST http://localhost:8080/run-test \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Verify the login flow",
    "packageName": "com.example.myapp",
    "steps": [
      "Tap Login",
      "Enter username test@example.com",
      "Enter password hunter2",
      "Tap Submit",
      "Verify Profile screen is visible"
    ]
  }'

packageName is the platform-native identifier of the app under test — Android package id, iOS bundle id, or the bundle of a React Native app. It is supplied by the caller (or set in the dashboard's Settings → App Identifier field); there is no hardcoded default. Full walkthrough: docs/getting-started.md.

---

Architecture

A Kotlin/Ktor server receives a scenario, a Koog AIAgent reasons step-by-step, and a platform-aware tool layer drives the device under test.

flowchart LR
    U[User] -->|writes scenario| FE[Web Dashboard<br/>React + Vite]
    FE -->|POST /run-test| API[Ktor HTTP API]
    API --> AGENT[MobileTestAgent<br/>Koog AIAgent]
    AGENT <-->|reasoning| LLM[(LLM<br/>DeepSeek / Gemini /<br/>Claude / OpenRouter / Ollama)]
    AGENT -->|Tool calls| TOOLS[MobileTestTools<br/>platform-aware]
    TOOLS --> AND[Android<br/>device / emulator]
    TOOLS --> IOS[iOS<br/>device / simulator]
    TOOLS --> RN[React Native<br/>app on Android or iOS]
    AGENT -->|result| API
    API -->|JSON| FE
    FE -.->|scenarios| FS[(Firebase Firestore)]

Detailed design lives in docs/:

Doc	What it covers
Architecture	Runtime topology, request lifecycle, module map
Getting Started	Prerequisites, env vars, first test run
HTTP API	POST /run-test, POST /stop-test, POST /config, payloads and errors
AI Agent	Strategy graph, system prompt, LLM executors
Tools	Full MobileTestTools catalog and ADB/UiAutomator utilities
Frontend (web)	React 19 + Vite dashboard, theming, i18n, Firestore
Dependencies	Every third-party library used in backend and frontend

---

References

• Koog Documentation — the agentic framework powering the LLM ↔ tool loop
• Building an Agentic AI Mobile Tester with Koog and Kotlin — the blog post behind this project
• mobile-tester-agent-sample-app — sample Android app under test
• How to Actually Test Autonomous AI Agents

---

License

Released under the MIT License. © 2026 Maiko Trindade.