Skip to main content

Smoke Testing Your App

Start with a short, low-risk run. Once the built-in iOS Settings smoke test works, point QAosMonkey at your app bundle or package id.

The included qaos-monkey.ios-sim.config.ts uses a deterministic, Settings-specific fixture only to verify the wiring. Do not reuse its model.command for your app: configure a real model provider for exploratory testing.

iOS​

Find your simulator UDID:

npx agent-device devices --platform ios --json
xcrun simctl list devices booted

Configure the driver:

const simulatorUdid = "YOUR_SIMULATOR_UDID";
const agentDevice = ["npx", "agent-device", "--platform", "ios", "--udid", simulatorUdid];

Android​

Find your emulator serial:

npx agent-device devices --platform android --json
adb devices

Configure the driver:

const emulatorSerial = "emulator-5554";
const agentDevice = ["npx", "agent-device", "--platform", "android", "--serial", emulatorSerial];

Run​

npm run qaosmonkey -- run --config qaos-monkey.config.ts

If you installed QAosMonkey from npm, use:

npx qaosmonkey run --config qaos-monkey.config.ts

Every new run restarts the target app before taking its first snapshot. For an explicit agent-device launch command, use open <bundle-or-package-id> --relaunch; QAosMonkey also adds --relaunch automatically when it recognizes an agent-device open command.

Use -- only with npm run qaosmonkey -- ..., not with npx qaosmonkey.

QAosMonkey prints [qaosmonkey] progress lines while it runs, including each step, screen observation, model call, chosen action, device execution, and result. CLI model providers also emit heartbeat messages every 10 seconds while QAosMonkey waits for Codex CLI or Claude Code to return a decision.

To silence progress logs:

QAOSMONKEY_QUIET=1 npm run qaosmonkey -- run --config qaos-monkey.config.ts

Run artifacts are written to .qaos-monkey/runs/<runId>/ by default. Each run directory contains:

  • report.md: human-readable report.
  • report.json: machine-readable report.
  • state.json: latest persisted run state.
  • state.jsonl: append-only per-step event trace for debugging.
  • screenshots/: screenshots captured during the run.

You can change the artifact root with reporting.outputDir.

When a Run Stops​

QAosMonkey stops when the model returns finish after minimumStepsBeforeFinish and no safe coverage frontier remains, when maxSteps is reached, when timeLimitSeconds is reached, or when a human aborts a paused run.

The model is instructed to finish only after it has satisfied the goal and mustTest guidance, reached the step budget, or found no meaningful unexplored controls left. Coverage-guided mode ignores early finish decisions, tries safe unexplored controls, and backtracks out of exhausted branches. Known no-ops, failed actions, unchanged waits, and short navigation cycles are not repeated indefinitely.