ios-simulator

# iOS Simulator Automation This skill provides a **Node-only** CLI wrapper around: - `xcrun simctl` for simulator/device/app management - `idb` for **accessibility-tree** inspection + synthesised UI input (tap/text/button) It is designed for **AI agents**: minimal, structured output by default, with opt-in detail. ## Important constraints - **Must run on macOS** with Xcode Command Line Tools (or Xcode) available. - If the ClawdBot gateway is not macOS, run these commands on a connected **macOS node** (see “Remote macOS node” below). - `idb` is optional, but required for UI tree / semantic tapping. (Install steps below.) ## Quick start ```bash # 1) Sanity check node {baseDir}/scripts/ios-sim.mjs health # 2) List simulators (compact) node {baseDir}/scripts/ios-sim.mjs list # 3) Select a default simulator (writes .ios-sim-state.json in the current dir) node {baseDir}/scripts/ios-sim.mjs select --name "iPhone" --runtime "iOS" --boot # 4) Install + launch an .app node {baseDir}/scripts/ios-sim.mjs app install --app path/to/MyApp.app node {baseDir}/scripts/ios-sim.mjs app launch --bundle-id com.example.MyApp # 5) Inspect current UI (requires idb) node {baseDir}/scripts/ios-sim.mjs ui summary node {baseDir}/scripts/ios-sim.mjs ui tap --query "Log in" node {baseDir}/scripts/ios-sim.mjs ui type --text "hello world" # 6) Screenshot node {baseDir}/scripts/ios-sim.mjs screenshot --out artifacts/screen.png ``` ## Remote macOS node If you are not on macOS, run the same commands on the macOS node using ClawdBot’s node execution (e.g. `exec` with `host: node` / node tools). Ensure the skill folder exists on that node, or copy it there. ## Output conventions (token-efficient) - Default output: **single-line JSON** (small summary object). - Add `--pretty` to pretty-print JSON. - Add `--text` for a short human-readable summary (when provided by the command). - Commands that can be huge (`ui tree`, `list --full`) are **opt-in**. ## State / default UDID `select` writes a state file (default: `./.ios-sim-state.json`) that stores the chosen UDID. All commands accept `--udid <UUID>` and otherwise fall back to the state file. Override location with: - `IOS_SIM_STATE_FILE=/path/to/state.json` ## Dependency notes ### Xcode / simctl availability If `xcrun` cannot find `simctl`, ensure Xcode CLI tools are selected (via Xcode settings or `xcode-select`) and run the first-launch setup: - `xcodebuild -runFirstLaunch` ### idb (for accessibility automation) Install `idb_companion` and the `idb` CLI: ```bash brew tap facebook/fb brew install idb-companion python3 -m pip install --upgrade fb-idb ``` ## Safety tiers | Tier | Commands | Notes | |------|----------|------| | SAFE | `list`, `health`, `boot`, `shutdown`, `screenshot`, `ui *` | No data loss | | CAUTION | `privacy *`, `push`, `clipboard *`, `openurl` | Alters simulator/app state | | DANGEROUS | `erase`, `delete` | Requires `--yes` | ## Command index All commands live under: ```bash node {baseDir}/scripts/ios-sim.mjs <command> [subcommand] [flags] ``` ### Core simulator lifecycle - `list [--full]` - `select --name <substr> [--runtime <substr>] [--boot]` - `boot [--udid <uuid>] [--wait]` - `shutdown [--udid <uuid>|--all]` - `erase --yes [--udid <uuid>|--all]` - `delete --yes [--udid <uuid>]` - `create --name <name> --device-type <substr> --runtime <substr>` ### App management - `app install --app <path/to/App.app> [--udid ...]` - `app uninstall --bundle-id <id> [--udid ...]` - `app launch --bundle-id <id> [--udid ...] [-- <args...>]` - `app terminate --bundle-id <id> [--udid ...]` - `app container --bundle-id <id> [--type data|app] [--udid ...]` ### Screenshots & video - `screenshot --out <file.png> [--udid ...]` - `record-video --out <file.mp4> [--udid ...]` (runs until Ctrl+C) ### Clipboard / URL - `clipboard get [--udid ...]` - `clipboard set --text <text> [--udid ...]` - `openurl --url <url> [--udid ...]` ### Simulator permissions & push notifications - `privacy grant --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `privacy revoke --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `privacy reset --bundle-id <id> --service <svc[,svc...]> [--udid ...]` - `push --bundle-id <id> --payload <json-string> [--udid ...]` ### Logs - `logs show [--last 5m] [--predicate <expr>] [--udid ...]` ### Accessibility-driven UI automation (requires idb) - `ui summary [--limit 12]` - `ui tree` (full UI JSON array) - `ui find --query <text> [--limit 20]` - `ui tap --query <text>` (find + tap best match) - `ui tap --x <num> --y <num>` (raw coordinate tap) - `ui type --text <text>` - `ui button --name HOME|LOCK|SIRI|SIDE_BUTTON|APPLE_PAY` ## Troubleshooting See: [references/TROUBLESHOOTING.md](references/TROUBLESHOOTING.md)