ios-simulator

What this skill does

# iOS Simulator

Manage iOS Simulator devices and test app behavior from the command line using `xcrun simctl`. Covers the full device lifecycle, app deployment, push and location simulation, permission control, screenshot and video recording, log streaming, and compile-time simulator detection.

For common subcommands, syntax, and examples, see [references/simctl-commands.md](references/simctl-commands.md).

## Contents

- [Device Lifecycle](#device-lifecycle)
- [App Install and Launch](#app-install-and-launch)
- [Testing Workflows](#testing-workflows)
- [Screenshot and Video Recording](#screenshot-and-video-recording)
- [Log Streaming](#log-streaming)
- [Compile-Time Simulator Detection](#compile-time-simulator-detection)
- [Simulator Limitations](#simulator-limitations)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Device Lifecycle

### Listing Devices and Runtimes

```bash
# List all available simulators grouped by runtime
xcrun simctl list devices available

# List installed runtimes
xcrun simctl list runtimes

# List only booted devices
xcrun simctl list devices booted

# JSON output for scripting
xcrun simctl list -j devices available
```

Parse JSON output to find a specific device programmatically. See [references/simctl-commands.md](references/simctl-commands.md) for `jq` parsing examples.

### Creating a Device

```bash
# Find available device types and runtimes
xcrun simctl list devicetypes
xcrun simctl list runtimes

# Create a device — returns the new UDID
xcrun simctl create "My Test Phone" "iPhone 16 Pro" "com.apple.CoreSimulator.SimRuntime.iOS-18-4"
```

Device types and runtime identifiers in examples throughout this skill are illustrative. Run `simctl list devicetypes` and `simctl list runtimes` to find the identifiers available on your system.

The returned UDID identifies the device for all subsequent commands. Use descriptive names to distinguish devices in `simctl list` output.

### Boot, Shutdown, Erase, Delete

```bash
# Boot a specific device
xcrun simctl boot <UDID>

# Boot if needed and wait until the device is ready
xcrun simctl bootstatus <UDID> -b

# Shutdown a running device
xcrun simctl shutdown <UDID>

# Factory reset — wipes all data, keeps the device
xcrun simctl erase <UDID>

# Delete a specific device
xcrun simctl delete <UDID>

# Delete all devices not available in the current Xcode
xcrun simctl delete unavailable

# Shutdown everything
xcrun simctl shutdown all
```

Use `booted` as a UDID shorthand when exactly one simulator is running:

```bash
xcrun simctl shutdown booted
```

If multiple simulators are booted, `booted` picks one of them non-deterministically. Prefer explicit UDIDs when running parallel simulators.

In scripts and CI, use `xcrun simctl bootstatus <UDID> -b` before install, launch, push, or location commands. If you call `simctl boot` separately, follow it with `xcrun simctl bootstatus <UDID>` before continuing.

## App Install and Launch

### Installing an App

```bash
# Build for simulator first
xcodebuild build \
    -scheme MyApp \
    -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
    -derivedDataPath build/

# Boot and wait for SpringBoard/services before install
xcrun simctl bootstatus <UDID> -b

# Install the .app bundle
xcrun simctl install <UDID> build/Build/Products/Debug-iphonesimulator/MyApp.app
```

The path must point to a `.app` directory built for the simulator architecture, not a `.ipa` file.

### Launching and Terminating

```bash
# Launch by bundle ID
xcrun simctl launch booted com.example.MyApp

# Launch and stream stdout/stderr to the terminal
xcrun simctl launch --console booted com.example.MyApp

# Pass launch arguments
xcrun simctl launch booted com.example.MyApp --reset-onboarding -AppleLanguages "(fr)"

# Terminate a running app
xcrun simctl terminate booted com.example.MyApp
```

`--console` is useful for debugging — it shows `print()` and `os_log` output directly in the terminal.

### App Container Paths

```bash
# App bundle location
xcrun simctl get_app_container booted com.example.MyApp app

# Data container (Documents, Library, tmp)
xcrun simctl get_app_container booted com.example.MyApp data

# Shared app group container
xcrun simctl get_app_container booted com.example.MyApp group.com.example.shared
```

Use these paths to inspect sandboxed files, databases, or UserDefaults during debugging.

## Testing Workflows

### Push Notification Simulation

Create a JSON payload file:

```json
{
    "aps": {
        "alert": {
            "title": "New Message",
            "body": "You have a new message from Alice"
        },
        "badge": 3,
        "sound": "default"
    },
    "customKey": "customValue"
}
```

Send it to the Simulator:

```bash
# Send push payload from file
xcrun simctl push booted com.example.MyApp payload.json

# Pipe payload from stdin
echo '{"aps":{"alert":"Quick test"}}' | xcrun simctl push booted com.example.MyApp -
```

This simulates local delivery only — no APNs connection is involved. Use this to test payload handling, notification display, and notification actions. Always verify on a real device before shipping to confirm APNs delivery works end to end.

### Location Simulation

```bash
# Set a fixed coordinate (latitude, longitude)
xcrun simctl location booted set 37.3349,-122.0090

# List available predefined scenarios
xcrun simctl location booted list

# Run a predefined scenario
xcrun simctl location booted run "City Run"

# Follow custom command-line waypoints
xcrun simctl location booted start --speed=15 --interval=1 \
    37.3349,-122.0090 37.3317,-122.0307

# Read waypoints from stdin, one "lat,lon" pair per line
printf "37.3349,-122.0090\n37.3317,-122.0307\n" | \
    xcrun simctl location booted start --distance=100 -

# Clear the simulated location
xcrun simctl location booted clear
```

Use `set` for one coordinate, `run` for predefined scenario names, and `start` for custom waypoint routes. The command boundary matters: `simctl location run` accepts built-in scenario names (e.g., "City Run", "Freeway Drive"), not GPX file paths; `simctl location start` is the command-line path for custom coordinate waypoints. Use Xcode's Debug > Simulate Location menu for GPX-based routes.

Location simulation affects all apps using Core Location on the booted device. Clear the location when done to avoid unexpected test results.

### Privacy Permissions

```bash
# Grant a permission
xcrun simctl privacy booted grant photos com.example.MyApp

# Revoke a permission
xcrun simctl privacy booted revoke microphone com.example.MyApp

# Reset all permissions for the app
xcrun simctl privacy booted reset all com.example.MyApp
```

Common service names: `photos`, `microphone`, `contacts`, `calendar`, `reminders`, `location`, `location-always`, `motion`, `siri`. See [references/simctl-commands.md](references/simctl-commands.md) for the full list.

Pre-granting permissions in CI avoids system permission dialogs that block automated test runs, but it can mask missing usage description keys. Keep the required Info.plist privacy strings in place and still test the normal prompt flow.

### Deep Links and URLs

```bash
# Open a URL (triggers universal links or custom URL schemes)
xcrun simctl openurl booted "https://example.com/product/123"

# Custom URL scheme
xcrun simctl openurl booted "myapp://settings/notifications"
```

For universal links, the app's associated domains entitlement must be configured. The Simulator uses the `apple-app-site-association` file from the domain.

### Status Bar Overrides

```bash
# Set a clean status bar for screenshots
xcrun simctl status_bar booted override \
    --time "9:41" \
    --batteryState charged \
    --batteryLevel 100 \
    --cellularMode active \
    --cellularBars 4 \
    --wifiBars 3 \
    --operatorName ""

# Clear all overrides
xcrun simctl status_bar booted clear
```

Use status bar overrides to produce consistent App Store