ios-debugger

Files (1)

• SKILL.md

SKILL.md (first lines)

# ABOUTME: XcodeBuildMCP integration for building, running, and debugging iOS apps via CLI
# ABOUTME: Simulator control, UI interaction, log capture, screenshot automation

# iOS Debugger

## When to Invoke
- Build/run iOS apps without Xcode UI
- Automate simulator interactions
- Capture app logs programmatically
- UI testing via CLI
- CI/CD iOS workflows

## Capabilities
- Build and run on booted simulator
- Interact with simulator UI (tap, type, gestures)
- Capture and filter app logs
- Take screenshots
- Install/uninstall apps

## Prerequisites

```bash
# Check if simulator is booted (pick <booted device> from this list, do not hardcode a model)
xcrun simctl list devices | grep Booted

# Boot simulator if needed
xcrun simctl boot "<booted device>"
```

Throughout this file, `<booted device>` is a placeholder: substitute the device name or UDID from `xcrun simctl list devices | grep Booted`.

## Build and Run

```bash
# Build for simulator
xcodebuild -workspace MyApp.xcworkspace \
    -scheme MyApp \
    -sdk iphonesimulator \
    -destination 'platform=iOS Simulator,name=<booted device>' \
    build

# Install app on simulator
xcrun simctl install booted path/to/MyApp.app

# Launch app
xcrun simctl launch booted com.example.myapp
```

## UI Interaction

`simctl io` does NOT do taps/typing/swipes (it only handles `screenshot`, `recordVideo`, `enumerate`, `poll`). For UI automation pick one of:

```bash
# Screenshot / screen recording (simctl's actual io surface)
xcrun simctl io booted screenshot screenshot.png
xcrun simctl io booted recordVideo demo.mov   # stop with Ctrl-C

# Taps/typing/gestures option 1: XCUITest (robust, accessibility-ID based)
xcodebuild test -workspace App.xcworkspace -scheme AppUITests \
    -destination 'platform=iOS Simulator,name=<booted device>'

# Taps/typing/gestures option 2: Meta's idb (brew install idb-companion; pip install fb-idb)
idb ui tap 200 400
idb ui text "Hello World"
idb ui swipe 200 600 200 200 --duration 0.5
```

If a command shape is not listed here, verify with `xcrun simctl help io` before using it: plausible-looking subcommands such as `simctl io tap` do not exist.

## Log Capture

```bash
# Stream all logs from booted simulator
xcrun simctl spawn booted log stream --predicate 'processImagePath CONTAINS "MyApp"'

# Filter by subsystem
xcrun simctl spawn booted log stream --predicate 'subsystem == "com.example.myapp"'

# Capture logs to file
xcrun simctl spawn booted log stream \
    --predicate 'processImagePath CONTAINS "MyApp"' \
    > app.log &
```

## Common Workflows

### Reset Simulator
```bash
# Erase all data
xcrun simctl erase "<booted device>"

# Shutdown and boot
xcrun simctl shutdown "<booted device>"
xcrun simctl boot "<booted device>"
```

## Tips
- Always check simulator is booted before commands
- Use `log stream` predicates to filter noise
- Coordinate-based taps are fragile (prefer accessibility IDs in XCTest)
- Capture screenshots for visual regression tests
- Use `xcrun simctl openurl` to test deep links

## Integration with Tests
```bash
# Run XCTests on simulator
xcodebuild test \
    -workspace App.xcworkspace \
    -scheme App \
    -destination 'platform=iOS Simulator,name=<booted device>' \
    -resultBundlePath TestResults.xcresult
```

From maroffo/claude-forge, MIT.

More from maroffo/claude-forge