Skip to main content

Configuration

QAosMonkey is configured with a TypeScript file that exports a config object.

const config = {
  app: {
    platform: "ios",
    name: "My App",
    bundleId: "com.example.app",
    launchCommand: ["npx", "agent-device", "--platform", "ios", "--udid", "YOUR_SIMULATOR_UDID", "open", "com.example.app", "--relaunch"]
  },
  device: {
    driver: "agent-device",
    command: ["npx", "agent-device", "--platform", "ios", "--udid", "YOUR_SIMULATOR_UDID"]
  },
  model: {
    provider: "codex-cli",
    command: ["codex", "exec", "--json", "--skip-git-repo-check"],
    model: "gpt-5",
    temperature: 0
  },
  exploration: {
    goal: "Smoke test login, navigation, empty states, and obvious broken screens.",
    persona: "You are an autonomous Chaos Monkey QA agent. Be curious, adversarial, and systematic.",
    strategy: "coverage-guided",
    seed: 0,
    maxConsecutiveNoProgress: 2,
    mustTest: [
      "Login must work with the configured test account.",
      "Create post: after tapping Post, the new post should be immediately visible.",
      "Blocking a user: the blocked user should no longer be able to see the blocker profile."
    ],
    maxSteps: 20,
    minimumStepsBeforeFinish: 8,
    timeLimitSeconds: 600,
    destructiveLevel: "low",
    maxRepeatedScreenVisits: 4,
    excludedActions: [],
    excludedScreens: ["Payment", "Delete account"],
    allowlistRiskyAreas: []
  },
  humanInput: {
    provider: "cli"
  },
  reporting: {
    outputDir: ".qaos-monkey/runs",
    retainScreenshots: true
  }
};

export default config;

A new run terminates and relaunches the target app before the first snapshot. QAosMonkey adds --relaunch to recognized agent-device open commands automatically. If launchCommand invokes another custom launcher, that command must provide equivalent restart behavior itself.

Model Commands​

If codex is not on PATH, set the full executable path:

command: ["/Applications/Codex.app/Contents/Resources/codex", "exec", "--json", "--skip-git-repo-check"]

CLI providers receive the full QAosMonkey prompt on stdin and must print one JSON decision on stdout.

Required Coverage Guidance​

Use exploration.goal for the broad mission and exploration.mustTest for specific behavior that must be exercised. Keep these items in natural language and describe the outcome you care about, not the exact sequence of taps.

exploration: {
  goal: "Explore the social app with emphasis on auth, posting, profile visibility, and destructive edge cases.",
  mustTest: [
    "The following features must at least work: login, sign up, create post, delete post.",
    "When creating a post, make sure the post is immediately visible after tapping Post.",
    "When blocking a user, make sure the blocked user can no longer see the blocker profile."
  ]
}

QAosMonkey passes this list to the model on every decision. The model should prioritize it as required coverage while still choosing the concrete route through the app.

Deterministic Coverage Guidance​

strategy: "coverage-guided" is the default. QAosMonkey assigns semantic identities to controls, records successful and unsuccessful attempts, and backtracks toward screens with unexplored controls. Equal-priority controls are ordered using seed, so changing the seed produces a different but reproducible tie order.

A valid model action that has not already been attempted is preserved. The runner intervenes when a proposal is invalid, repeats a known no-op or failure, closes a navigation cycle, or finishes while a safe frontier remains. Use strategy: "model-led" as a compatibility escape hatch.