/ios-simulator-skill

name: ios-simulator-skill
version: 1.8.0
description: Build, test, and drive iOS apps in the Simulator with 31 token-efficient scripts. Use when asked to build or test an Xcode project, launch an app on a simulator, tap/type/swipe through its UI by accessibility label, take screenshots or visual diffs, audit accessibility, read logs or diagnose hangs, or manage simulators (boot, erase, permissions, location, push, appearance). macOS only; needs Xcode, Python 3.12+ and idb.

iOS Simulator Skill

Build, test, and automate iOS applications using accessibility-driven navigation and structured data instead of pixel coordinates.

Quick Start

# 1. Check environment
bash scripts/sim_health_check.sh

# 2. Launch app
python3 scripts/app_launcher.py --launch com.example.app

# 3. Map screen to see elements
python3 scripts/screen_mapper.py

# 4. Tap button
python3 scripts/navigator.py --find-text "Login" --tap

# 5. Enter text
python3 scripts/navigator.py --find-type TextField --enter-text "user@example.com"

**Paths:** `scripts/` is relative to the directory containing this SKILL.md, not the user's project. Examples write `scripts/...` for brevity; run them by absolute path from the user's project (e.g. `python3 <skill-dir>/scripts/navigator.py ...`) so relative Xcode project paths still resolve.

All scripts support `--help` for detailed options; most support `--json` for machine-readable output.

Navigation Strategy

**Always prefer the accessibility tree over screenshots for navigation.** The accessibility tree gives you element types, labels, frames, and tap targets — structured data that's cheaper and more reliable than image analysis.

Use this priority: 1. `screen_mapper.py` → structured element list (5-7 lines, ~10 tokens) 2. `navigator.py --find-text/--find-type/--find-id` → semantic interaction 3. Screenshots → only for visual verification, bug reports, or visual diff

Screenshots cost 1,600–6,300 tokens depending on size. The accessibility tree costs 10–50 tokens in default mode.

31 Production Scripts

Build & Development (2 scripts)

1. **build_and_test.py** - Build Xcode projects, run tests, parse results with progressive disclosure

• Build with live result streaming
• Parse errors and warnings from xcresult bundles
• Retrieve detailed build logs on demand
• `--run` builds, installs and launches the app in one call: `Launched: <bundle> on <device> (pid N)`
• Tests that never started (parallel clone failed to boot) report `Tests: NOT RUN`, not FAIL; retry with `--no-parallel`
• Options: `--project`, `--scheme`, `--clean`, `--test`, `--run`, `--no-parallel`, `--verbose`, `--json`

2. **log_monitor.py** - Real-time log monitoring with intelligent filtering

• Stream logs or capture by duration
• Filter by severity (error/warning/info/debug)
• Deduplicate repeated messages
• Options: `--app`, `--severity`, `--follow`, `--duration`, `--output`, `--json`

Device State (4 scripts)

3. **appearance.py** - Control simulator appearance: dark mode, Dynamic Type size, contrast, and locale/region

• Toggle light/dark theme via `xcrun simctl ui`
• Set Dynamic Type size with friendly aliases (XS through AX5)
• `--contrast high|normal` toggles Increase Contrast and reads it back to confirm; `--reset` also restores normal contrast
• Write locale and region defaults; optional app restart via `--bundle-id`
• RTL flagged automatically for ar/he/fa/ur/yi locales
• Options: `--theme`, `--text-size`, `--contrast`, `--locale`, `--region`, `--reset`, `--bundle-id`, `--udid`, `--json`, `--verbose`

4. **location.py** - Simulate GPS coordinates, named city presets, and GPX scenario playback

• Fix a coordinate with `--lat`/`--lng` or pick a city with `--city`
• Play a built-in scenario (City Run, Freeway Drive, etc.) via `--gpx <scenario>`
• Animate multi-waypoint paths with configurable speed via `--waypoints` and `--speed`
• Clear simulated location with `--clear`; list available scenarios with `--list-scenarios`
• Options: `--lat`, `--lng`, `--city`, `--gpx`, `--waypoints`, `--speed`, `--clear`, `--list-scenarios`, `--udid`, `--json`, `--verbose`

5. **media.py** - Seed or empty the photo library for photo-picker tests

• `--add a.jpg b.png` via `xcrun simctl addmedia`
• `--clear --yes` empties the library via `idb photos clear` (idb 1.7+); `--clear --yes --add` leaves exactly the added files
• Without `--yes`, `--clear` refuses if the library has photos (they can't be recovered): ask the user first
• Fails fast on a missing file
• Options: `--add`, `--clear`, `--yes`, `--udid`, `--json`

6. **duo.py** - Experimental iPhone Duo hinge and interface orientation controls

• Requires an explicit booted Duo `--udid`; no automatic device selection
• Read observed angle, active cover/inner display ID and rotation (default or `--state`)
• `--pose closed|partial|open` (0°/90°/180°), `--angle 0..180`, or `--orientation portrait|landscape|portrait-upside-down|landscape-flipped`
• Changes verify observed readback; hinge endpoints also verify cover/inner display activation
• Bundled Objective-C helper compiles and signs with the selected Xcode on first use; no extra CLI
• Private APIs are experimental; inner-display coordinate touch routing is unverified
• Options: `--udid`, `--state`, `--pose`, `--angle`, `--orientation`, `--json`, `--verbose`

Navigation & Interaction (5 scripts)

7. **screen_mapper.py** - Analyze current screen and list interactive elements

• Element type breakdown
• Interactive button list
• Text field status
• If labelled elements cover under 10% of the screen, adds a `Coverage:` line suggesting `--deep`
• `--deep` reads through idb's axbridge backend (idb 1.7+): also sees Safari/WKWebView content

and in-app alerts the default read misses, plus many unlabelled container views. It turns on the device's accessibility automation mode (not res