---

name: ios-simulator-skill version: 1.5.0 description: 29 production-ready scripts for iOS app testing, building, and automation. Provides semantic UI navigation, build automation, accessibility testing, and simulator lifecycle management. Optimized for AI agents with minimal token output.

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
python scripts/app_launcher.py --launch com.example.app

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

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

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

All scripts support --help for detailed options and --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.

29 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
   • Options: --project, --scheme, --clean, --test, --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 (2 scripts)

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

   • Toggle light/dark theme via xcrun simctl ui
   • Set Dynamic Type size with friendly aliases (XS through AX5)
   • 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, --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

Navigation & Interaction (5 scripts)

5. screen_mapper.py - Analyze current screen and list interactive elements

   • Element type breakdown
   • Interactive button list
   • Text field status
   • Options: --verbose, --hints, --json

6. navigator.py - Find and interact with elements semantically

   • Find by text (fuzzy matching)
   • Find by element type
   • Find by accessibility ID
   • Enter text or tap elements
   • Options: --find-text, --find-type, --find-id, --tap, --enter-text, --json

7. gesture.py - Perform swipes, scrolls, pinches, and complex gestures

   • Directional swipes (up/down/left/right)
   • Multi-swipe scrolling
   • Pinch zoom
   • Long press
   • Pull to refresh
   • Options: --swipe, --scroll, --pinch, --long-press, --refresh, --json

8. keyboard.py - Text input and hardware button control

   • Type text (fast or slow)
   • Special keys (return, delete, tab, space, arrows)
   • Hardware buttons (home, lock, volume, screenshot)
   • Key combinations
   • Options: --type, --key, --button, --slow, --clear, --dismiss, --json

9. app_launcher.py - App lifecycle management

   • Launch apps by bundle ID
   • Terminate apps
   • Install/uninstall from .app bundles
   • Deep link navigation
   • List installed apps
   • Check app state
   • Pass launch arguments (--args) and environment variables (--env KEY=VALUE, injected as SIMCTL_CHILD_*) to the app on launch/restart
   • Options: --launch, --terminate, --restart, --install, --uninstall, --open-url, --list, --state, --args, --env, --wait-for-debugger

Testing & Analysis (9 scripts)

10. accessibility_audit.py - Check WCAG compliance on current screen

    • Critical issues (missing labels, empty buttons, no alt text)
    • Warnings (missing hints, small touch targets)
    • Info (missing IDs, deep nesting)
    • Options: --verbose, --output, --json

11. visual_diff.py - Compare two screenshots for visual changes

    • Pixel-by-pixel comparison
    • Threshold-based pass/fail
    • Generate diff images
    • Options: --threshold, --output, --details, --json

12. test_recorder.py - Automatically document test execution

    • Capture screenshots and accessibility trees per step
    • Generate markdown reports with timing data
    • Options: --test-name, --output, --verbose, --json

13. app_state_capture.py - Create comprehensive debugging snapshots

    • Screenshot, UI hierarchy, app logs, device info
    • Markdown summary for bug reports
    • Options: --app-bundle-id, --output, --log-lines, --json

14. sim_health_check.sh - Verify environment is properly configured

    • Check macOS, Xcode, simctl, IDB, Python
    • List available and booted simulators
    • Verify Python packages (Pillow)

15. model_inspector.py - Inspect Core Data and SwiftData models from project files

    • Parse .xcdatamodeld packages (entities, attributes, relationships)
    • Detect model versions and current active version
    • Best-effort SwiftData @Model class extraction
    • Raw source dump for any model on demand (--raw ModelName)
    • Options: --project-path, --core-data-only, --swiftdata-only, --show-versions, --raw, --verbose, --json

16. container.py - Inspect app sandbox: files, UserDefaults, and Core Data store paths

    • List data container files at configurable depth via --ls
    • Read files with auto-detected plist decoding via --cat (large files cached)
    • Dump UserDefaults as key=value or JSON via --userdefaults
    • Locate .sqlite / .sqlite-wal / .sqlite-shm stores via --core-data-path
    • Export full container snapshot via --export
    • Options: --ls, --cat, --userdefaults, --core-data-path, --export, --udid, --json, --verbose

17. hang_watcher.py (HangBuster) - Record + summarise os_log hang events with progressive disclosure

    • Session mode (HangBuster, agent-native): start a detached recorder, interact with the simulator, stop for a token-tight summary
      • --start → returns a session ID; detached worker normalises + thresholds events on the fly
      • --stop SESSION_ID → emits ~80–120 token L1 summary (header + top-N clusters + drill hint)
      • --get-details SESSION_ID [--cluster N | --raw] → L2 full clusters or L3 per-event detail
      • --list-sessions / --clear-sessions [--older-than 24h] / --diff A B (cross-session regression report)
      • Filter pipeline: parse → normalise → threshold → bucket → cluster → aggregate → rank → format (in common/hang_pipeline.py)
      • --budget-tokens N picks the densest level (L0/L1/L2) that fits; --terse forces L0
      • --auto-sample captures a main-thread stack on first event per cluster (soft dependency: main_thread_sampler.py #62; graceful no-op if absent)
    • Raw capture mode (full fidelity for jq exploration): skip the clustering pipeline, dump every matching log line verbatim to raw.ndjson
      • --start --raw-capture [--max-size-mb 10] [--no-gzip] — spawns log stream --style ndjson
      • Per-session size cap (--max-size-mb, default 10) — worker stops cleanly on cap; extras.truncated=true
      • --stop gzips raw.ndjson → raw.ndjson.gz (~15–19× compression; --no-gzip opts out)
      • --get-details SESSION_ID on a raw session prints the path with a zcat | jq ... hint
    • Resilience (auto-restart on stream death): EOF or subprocess death triggers a stream_died event then a bounded restart with 2s backoff. After IOS_SIM_HANG_MAX_RESTARTS (default 3) the session is marked crashed, never left in stale running state. --list-sessions shows capture=Xs and restarts=N.
    • Cleanup is automatic: TTL prune (IOS_SIM_HANG_SESSION_TTL_HOURS, default 24h) + aggregate cap (IOS_SIM_HANG_TOTAL_CAP_MB, default 100 MB, oldest-first eviction) both run on every --start.
    • Legacy modes (unchanged for backward compat): --watch [--duration N] (live stream) and --since 5m (historical)
    • Filters: --bundle-id (post-parse — hang capture stays simulator-global so RunningBoard/SpringBoard events are kept), --predicate (also via IOS_SIM_HANG_PREDICATE)
    • All output supports --json; session storage at ~/.ios-simulator-skill/sessions/<id>/{meta.json,events.jsonl,summary.json,raw.ndjson.gz}

    Quick start (summarised mode):

    SID=$(python scripts/hang_watcher.py --start --min-hang-ms 200)
    # ... interact with the simulator (open sheets, scroll, navigate) ...
    python scripts/hang_watcher.py --stop $SID                  # token-tight L1 summary
    python scripts/hang_watcher.py --get-details $SID --cluster 1  # drill into cluster 1
    python scripts/hang_watcher.py --diff $SID_BASELINE $SID    # cross-session regression
    

    Quick start (raw capture + jq exploration):

    SID=$(python scripts/hang_watcher.py --start --raw-capture --max-size-mb 5)
    # ... interact with the simulator ...
    python scripts/hang_watcher.py --stop $SID
    # → "Session ...: raw mode, 737 lines, 0.96 MB → 0.05 MB gzipped"
    
    # Top processes by event count:
    zcat ~/.ios-simulator-skill/sessions/$SID/raw.ndjson.gz \
      | jq -s 'group_by(.processImagePath) | map({proc: (.[0].processImagePath | split("/") | last), n: length}) | sort_by(-.n) | .[:5]'
    
    # All RunningBoard assertion invalidations:
    zcat .../raw.ndjson.gz | jq -c 'select(.subsystem == "com.apple.runningboard" and (.eventMessage | startswith("Invalidating")))'
    
    # Hangs per minute:
    zcat .../raw.ndjson.gz | jq -r '.timestamp[:16]' | sort | uniq -c
    

18. localization_audit.py - Detect string catalog gaps, missing keys, and placeholder mismatches

    • Report missing and needs_review/new keys per locale in .xcstrings catalogs
    • Cross-reference catalog keys against Swift source (String(localized:) / NSLocalizedString) via --source
    • Flag placeholder count mismatches (%d, %@, %s, %lld) across locales
    • Legacy .strings and .stringsdict support via plistlib
    • CI-friendly --strict exits 2 on any finding
    • Options: --catalog, --source, --locale, --strict, --json, --verbose

Advanced Testing & Permissions (4 scripts)

19. clipboard.py - Manage simulator clipboard for paste testing

    • Copy text to clipboard
    • Test paste flows without manual entry
    • Options: --copy, --test-name, --expected, --json

20. status_bar.py - Override simulator status bar appearance

    • Presets: clean (9:41, 100% battery), testing (