iOS Simulator Skill

The hang_watcher.py script (HangBuster) records and summarizes os_log hang events using two modes:

1. Session Mode (Agent-Native)

Designed for interactive debugging. It uses a detached recorder that normalizes and clusters events to provide a token-efficient summary.

Workflow:

1. Start: SID=$(python scripts/hang_watcher.py --start --min-hang-ms 200)
2. Interact: Perform actions in the simulator.
3. Stop: python scripts/hang_watcher.py --stop $SID (returns an L1 summary).
4. Drill Down: python scripts/hang_watcher.py --get-details $SID --cluster 1 (returns L2 details).
5. Compare: python scripts/hang_watcher.py --diff $SID_BASELINE $SID (regression report).

2. Raw Capture Mode

Skips clustering for full-fidelity log dumping, ideal for jq exploration.

Workflow:

1. Start: SID=$(python scripts/hang_watcher.py --start --raw-capture --max-size-mb 5)
2. Stop: python scripts/hang_watcher.py --stop $SID
3. Explore: Use zcat and jq on the resulting .gz file in ~/.ios-simulator-skill/sessions/$SID/raw.ndjson.gz.

Key Options:

• --start: Begins a new session.
• --stop <SESSION_ID>: Ends session and summarizes.
• --get-details <SESSION_ID>: Provides deeper inspection.
• --raw-capture: Enables raw NDJSON capture.
• --max-size-mb: Sets a cap on the raw capture size.
• --min-hang-ms: Minimum duration for a hang to be recorded.

# Summarized mode workflow
SID=$(python scripts/hang_watcher.py --start --min-hang-ms 200)
# ... interact with simulator ...
python scripts/hang_watcher.py --stop $SID
python scripts/hang_watcher.py --get-details $SID --cluster 1

The scripts in this project follow several consistent patterns:

• Auto-UDID Detection: Most scripts automatically detect the booted simulator if the --udid flag is not provided.
• Device Name Resolution: You can use human-readable device names (e.g., "iPhone 16 Pro") instead of UDIDs; scripts resolve these automatically.
• Batch Operations: Use --all to target all simulators or --type <type> (e.g., --type iPhone) to filter by device type.
• Output Formats: Use --json for machine-readable output suitable for CI/CD. The default is concise human-readable text.
• Screenshot Sizing: To manage token usage, you can specify screenshot presets:
  • full: High detail (~5K tokens).
  • half: Default (~1.6K tokens).
  • quarter: Low detail (~800 tokens) for quick visual checks.
• Help: Every script supports the --help flag for detailed options and usage examples.

To automate iOS simulator tasks, follow this standard sequence of operations:

1. Verify environment: Ensure prerequisites are met. bash scripts/sim_health_check.sh
2. Launch app: Start your application using its bundle ID. python scripts/app_launcher.py --launch com.example.app
3. Analyze screen: Map the current UI to identify elements. python scripts/screen_mapper.py
4. Interact: Perform actions like tapping buttons or entering text. python scripts/navigator.py --find-text "Button" --tap
5. Verify: Run an accessibility audit to ensure UI compliance. python scripts/accessibility_audit.py
6. Debug: If issues occur, capture the full application state. python scripts/app_state_capture.py --app-bundle-id com.example.app

# Example sequence
bash scripts/sim_health_check.sh
python scripts/app_launcher.py --launch com.example.app
python scripts/screen_mapper.py
python scripts/navigator.py --find-text "Button" --tap
python scripts/accessibility_audit.py

Use the idb ui command suite to interact with the iOS Simulator via accessibility. These commands allow you to inspect the UI tree, tap specific coordinates, swipe, enter text, and identify elements at specific points.

Available UI Commands:

# Get accessibility tree
idb ui describe-all --json --nested > tree.json

# Basic interaction sequence
idb ui tap 200 400
idb ui text "username@example.com"
idb ui tap 200 500