droid-cua

AI-powered mobile testing desktop app for Android and iOS

Create, run, and manage mobile tests with natural language. The desktop app guides setup, connects to your target device or simulator, and turns AI exploration into reusable test scripts.

https://github.com/user-attachments/assets/b9e15a1d-8072-4a2f-a4c5-db180ae38620

droid-cua is a desktop app for AI-powered mobile testing.

It helps teams create, edit, and run tests for Android devices and emulators and iOS simulators on macOS using natural language instead of traditional test code.

Under the hood, droid-cua uses an AI agent to explore your app, execute actions, and save reusable test scripts that can also be run later in headless workflows.

1. Download the desktop app

• Mac: Download
• Mac (Intel): Download
• Windows: Download

2. Launch the app

Open the desktop app and choose the platform you want to test.

3. Add your credentials

Set your OpenAI API key in the app Settings screen, or log in with your Loadmill account.

4. Connect a target device

• Android: connect a device or select an emulator
• iOS: choose a simulator on macOS

5. Create or run a test

Use the desktop app to create a new test, edit an existing one, or run a saved script with live execution logs.

You can also keep project run history in a results folder and review past runs from desktop app reports.

• Android - Physical devices and emulators
• iOS - Simulators on macOS

Desktop app support:

• macOS: Android and iOS simulator workflows
• Windows: Android workflows only

Requirements

All platforms:

• OpenAI API key

Android:

• Android Debug Bridge (ADB)
• Android Emulator CLI for launchable emulators

iOS (macOS only):

• Xcode with iOS Simulator
• Appium
• XCUITest driver

• Desktop-first workflow - Create, run, and manage tests from one app
• Setup guidance - Configure API access and platform prerequisites in the app
• Device and simulator connection - Connect Android targets and iOS simulators
• Natural-language test creation - Describe flows in plain English
• Test management - Create, edit, save, and rerun reusable scripts
• Live execution logs - Watch actions and progress as tests run
• Reports and history - Review past runs from a project results folder inside the desktop app
• JUnit XML output - Write standard test reports for CI systems and external tooling
• Headless support - Reuse scripts in CLI and automation workflows

1. The desktop app connects to an Android device or emulator through ADB, or to an iOS simulator through Appium + XCUITest
2. Captures full-screen device screenshots
3. Scales down the screenshots for OpenAI model compatibility
4. Sends screenshots and user instructions to OpenAI's computer-use model
5. Receives structured actions such as click, scroll, type, keypress, wait, and drag
6. Rescales model outputs back to real device coordinates
7. Executes the actions on the device or simulator
8. Validates assertions and handles failures
9. Repeats until task completion

The desktop app is the primary way to use droid-cua.

For CI, scripting, or advanced workflows, droid-cua also includes a CLI for running saved instructions headlessly.

Desktop projects can also keep run reports in a results folder, including JUnit XML output that the app can read back as project history.

The recommended workflow is:

• design and debug tests in the desktop app,
• commit the .dcua file plus a headless CLI config file,
• run the same test headlessly in CI with --config for prompt parity.

Install:

npm install -g @loadmill/droid-cua

Examples:

# Interactive CLI
droid-cua

# Headless Android run
droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua

# Headless iOS simulator run
droid-cua --platform ios --avd "iPhone 16" --instructions tests/login.dcua

# Headless run with prompt-parity config
droid-cua --avd adb:emulator-5554 --instructions tests/login.dcua --config ci/droid-cua.json

Example headless config:

{
  "cuaModel": "gpt-5.4",
  "promptCustomizations": {
    "basePromptInstructions": "",
    "designModeInstructions": "",
    "executionModeInstructions": ""
  },
  "appContextEnabled": true,
  "appContextPath": "../tests/context.md",
  "contextOptimizationEnabled": true,
  "contextOptimizationThreshold": 20000
}

Typical CI-style usage:

droid-cua \
  --avd adb:emulator-5554 \
  --instructions tests/login.dcua \
  --config ci/droid-cua.json \
  --debug

Supported CLI options include:

• --avd
• --platform
• --instructions
• --config
• --cua-model
• --context
• --no-context
• --context-optimization-threshold
• --no-context-optimization
• --base-prompt
• --execution-prompt
• --base-prompt-file
• --execution-prompt-file
• --strict
• --no-strict
• --record
• --debug

Config and precedence rules:

• Use --config <file> to supply prompt-affecting settings for headless runs.
• CLI flags override config file values.
• --context overrides the config app-context path.
• --no-context disables app context entirely.
• Context Optimization is enabled by default with a 20000 input-token threshold.
• --context-optimization-threshold <tokens> sets the threshold and enables Context Optimization.
• --no-context-optimization disables Context Optimization.
• --base-prompt and --execution-prompt let you pass prompt customizations inline on the command line.
• --base-prompt-file and --execution-prompt-file override the corresponding prompt customizations from config.
• If both inline and file-based prompt overrides are provided, the inline prompt flags win.

Example without a config file:

droid-cua \
  --avd adb:emulator-5554 \
  --instructions tests/login.dcua \
  --context tests/context.md \
  --base-prompt "stop and look at the screen after every action you take."

Headless debug artifacts:

• --debug writes desktop-style structured JSONL artifacts under logs/.
• Each run creates logs/execution-<runId>-<timestamp>.jsonl.
• Each run also creates a sibling screenshot folder next to that JSONL file.
• Shared device events are written to logs/device-events.jsonl.
• --debug no longer creates the legacy logs/debug-*.log file for headless runs.
• If --debug and --record are both used, screenshots are written to both the debug artifacts folder and the legacy droid-cua-recording-<timestamp> folder.

Current headless behavior is documented in docs/headless-cli-spec.md.

© 2026 Loadmill. All rights reserved.