iOS Simulator Skill

# iOS Simulator Skill

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

Quick Start

```bash # 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 "[email protected]" ```

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.

1. Use this priority:
2. `screen_mapper.py` → structured element list (5-7 lines, ~10 tokens)
3. `navigator.py --find-text/--find-type/--find-id` → semantic interaction
4. 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.

21 Production Scripts

Build & Development (2 scripts)

1. build_and_test.py - Build Xcode projects, run tests, parse results with progressive disclosure
2. - Build with live result streaming
3. - Parse errors and warnings from xcresult bundles
4. - Retrieve detailed build logs on demand
5. - Options: `--project`, `--scheme`, `--clean`, `--test`, `--verbose`, `--json`

1. log_monitor.py - Real-time log monitoring with intelligent filtering
2. - Stream logs or capture by duration
3. - Filter by severity (error/warning/info/debug)
4. - Deduplicate repeated messages
5. - Options: `--app`, `--severity`, `--follow`, `--duration`, `--output`, `--json`

Navigation & Interaction (5 scripts)

1. screen_mapper.py - Analyze current screen and list interactive elements
2. - Element type breakdown
3. - Interactive button list
4. - Text field status
5. - Options: `--verbose`, `--hints`, `--json`

1. navigator.py - Find and interact with elements semantically
2. - Find by text (fuzzy matching)
3. - Find by element type
4. - Find by accessibility ID
5. - Enter text or tap elements
6. - Options: `--find-text`, `--find-type`, `--find-id`, `--tap`, `--enter-text`, `--json`

1. gesture.py - Perform swipes, scrolls, pinches, and complex gestures
2. - Directional swipes (up/down/left/right)
3. - Multi-swipe scrolling
4. - Pinch zoom
5. - Long press
6. - Pull to refresh
7. - Options: `--swipe`, `--scroll`, `--pinch`, `--long-press`, `--refresh`, `--json`

1. keyboard.py - Text input and hardware button control
2. - Type text (fast or slow)
3. - Special keys (return, delete, tab, space, arrows)
4. - Hardware buttons (home, lock, volume, screenshot)
5. - Key combinations
6. - Options: `--type`, `--key`, `--button`, `--slow`, `--clear`, `--dismiss`, `--json`

1. app_launcher.py - App lifecycle management
2. - Launch apps by bundle ID
3. - Terminate apps
4. - Install/uninstall from .app bundles
5. - Deep link navigation
6. - List installed apps
7. - Check app state
8. - Options: `--launch`, `--terminate`, `--install`, `--uninstall`, `--open-url`, `--list`, `--state`, `--json`

Testing & Analysis (5 scripts)

1. accessibility_audit.py - Check WCAG compliance on current screen
2. - Critical issues (missing labels, empty buttons, no alt text)
3. - Warnings (missing hints, small touch targets)
4. - Info (missing IDs, deep nesting)
5. - Options: `--verbose`, `--output`, `--json`

1. visual_diff.py - Compare two screenshots for visual changes
2. - Pixel-by-pixel comparison
3. - Threshold-based pass/fail
4. - Generate diff images
5. - Options: `--threshold`, `--output`, `--details`, `--json`

1. test_recorder.py - Automatically document test execution
2. - Capture screenshots and accessibility trees per step
3. - Generate markdown reports with timing data
4. - Options: `--test-name`, `--output`, `--verbose`, `--json`

1. app_state_capture.py - Create comprehensive debugging snapshots
2. - Screenshot, UI hierarchy, app logs, device info
3. - Markdown summary for bug reports
4. - Options: `--app-bundle-id`, `--output`, `--log-lines`, `--json`

1. sim_health_check.sh - Verify environment is properly configured
2. - Check macOS, Xcode, simctl, IDB, Python
3. - List available and booted simulators
4. - Verify Python packages (Pillow)

Advanced Testing & Permissions (4 scripts)

1. clipboard.py - Manage simulator clipboard for paste testing
2. - Copy text to clipboard
3. - Test paste flows without manual entry
4. - Options: `--copy`, `--test-name`, `--expected`, `--json`

1. status_bar.py - Override simulator status bar appearance
2. - Presets: clean (9:41, 100% battery), testing (11:11, 50%), low-battery (20%), airplane (offline)
3. - Custom time, network, battery, WiFi settings
4. - Options: `--preset`, `--time`, `--data-network`, `--battery-level`, `--clear`, `--json`

1. push_notification.py - Send simulated push notifications
2. - Simple mode (title + body + badge)
3. - Custom JSON payloads
4. - Test notification handling and deep links
5. - Options: `--bundle-id`, `--title`, `--body`, `--badge`, `--payload`, `--json`

1. privacy_manager.py - Grant, revoke, and reset app permissions
2. - 13 supported services (camera, microphone, location, contacts, photos, calendar, health, etc.)
3. - Batch operations (comma-separated services)
4. - Audit trail with test scenario tracking
5. - Options: `--bundle-id`, `--grant`, `--revoke`, `--reset`, `--list`, `--json`

Device Lifecycle Management (5 scripts)

1. simctl_boot.py - Boot simulators with optional readiness verification
2. - Boot by UDID or device name
3. - Wait for device ready with timeout
4. - Batch boot operations (--all, --type)
5. - Performance timing
6. - Options: `--udid`, `--name`, `--wait-ready`, `--timeout`, `--all`, `--type`, `--json`

1. simctl_shutdown.py - Gracefully shutdown simulators
2. - Shutdown by UDID or device name
3. - Optional verification of shutdown completion
4. - Batch shutdown operations
5. - Options: `--udid`, `--name`, `--verify`, `--timeout`, `--all`, `--type`, `--json`

1. simctl_create.py - Create simulators dynamically
2. - Create by device type and iOS version
3. - List available device types and runtimes
4. - Custom device naming
5. - Returns UDID for CI/CD integration
6. - Options: `--device`, `--runtime`, `--name`, `--list-devices`, `--list-runtimes`, `--json`

1. simctl_delete.py - Permanently delete simulators
2. - Delete by UDID or device name
3. - Safety confirmation by default (skip with --yes)
4. - Batch delete operations
5. - Smart deletion (--old N to keep N per device type)
6. - Options: `--udid`, `--name`, `--yes`, `--all`, `--type`, `--old`, `--json`

1. simctl_erase.py - Factory reset simulators without deletion
2. - Preserve device UUID (faster than delete+create)
3. - Erase all, by type, or booted simulators
4. - Optional verification
5. - Options: `--udid`, `--name`, `--verify`, `--timeout`, `--all`, `--type`, `--booted`, `--json`

Common Patterns

Auto-UDID Detection: Most scripts auto-detect the booted simulator if --udid is not provided.

Device Name Resolution: Use device names (e.g., "iPhone 16 Pro") instead of UDIDs - scripts resolve automatically.

Batch Operations: Many scripts support `--all` for all simulators or `--type iPhone` for device type filtering.

Output Formats: Default is concise human-readable output. Use `--json` for machine-readable output in CI/CD.

Help: All scripts support `--help` for detailed options and examples.

Screenshot Sizing: Screenshots are resized to save tokens. Presets: `full` (3-4 tiles, ~5K tokens), `half` (1 tile, ~1.6K tokens, default), `quarter` (1 tile, ~800 tokens, less detail). Use `quarter` for quick visual checks, `half` for readable UI, `full` only when pixel-level detail matters. Scripts that capture screenshots (`app_state_capture.py`, `test_recorder.py`) default to `half`.

Typical Workflow

1. Verify environment: `bash scripts/sim_health_check.sh`
2. Launch app: `python scripts/app_launcher.py --launch com.example.app`
3. Analyze screen: `python scripts/screen_mapper.py`
4. Interact: `python scripts/navigator.py --find-text "Button" --tap`
5. Verify: `python scripts/accessibility_audit.py`
6. Debug if needed: `python scripts/app_state_capture.py --app-bundle-id com.example.app`

Requirements

• macOS 12+
• Xcode Command Line Tools
• Python 3
• IDB (optional, for interactive features)

Documentation

• SKILL.md (this file) - Script reference and quick start
• README.md - Installation and examples
• CLAUDE.md - Architecture and implementation details
• references/ - Deep documentation on specific topics
• examples/ - Complete automation workflows

Key Design Principles

Semantic Navigation: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes.

Token Efficiency: Concise default output (3-5 lines) with optional verbose and JSON modes for detailed results.

Accessibility-First: Built on standard accessibility APIs for reliability and compatibility.

Zero Configuration: Works immediately on any macOS with Xcode. No setup required.

Structured Data: Scripts output JSON or formatted text, not raw logs. Easy to parse and integrate.

Auto-Learning: Build system remembers your device preference. Configuration stored per-project.

---

Use these scripts directly or let Claude Code invoke them automatically when your request matches the skill description.