Ios Simulator

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.

Contents

• Device Lifecycle
• App Install and Launch
• Testing Workflows
• Screenshot and Video Recording
• Log Streaming
• Compile-Time Simulator Detection
• Simulator Limitations
• Common Mistakes
• Review Checklist
• References

Device Lifecycle

Listing Devices and Runtimes

# 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 for jq parsing examples.

Creating a Device

# 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

# 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:

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

# 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

# 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

# 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:

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

Send it to the Simulator:

# 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

# 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

# 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 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

# 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

# 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 screenshots. Always clear overrides after capturing to avoid confusing other testing.

Screenshot and Video Recording

# Capture a screenshot
xcrun simctl io booted screenshot screenshot.png

# Record video (press Ctrl+C to stop)
xcrun simctl io booted recordVideo recording.mov

# Screenshot with specific display mask
xcrun simctl io booted screenshot --mask black screenshot.png

--mask options: ignored (default, no mask), alpha (transparent corners), black (black corners). Use alpha or black when capturing screenshots that show the device shape. The alpha mask is only supported for screenshots — video recording falls back to black.

Video recording continues until the process receives SIGINT (Ctrl+C). The recording is saved only after stopping — killing the process with SIGKILL loses the file.

Log Streaming

Basic Log Stream

# Stream all logs at debug level and above
xcrun simctl spawn booted log stream --level debug

# Filter by subsystem
xcrun simctl spawn booted log stream --level debug \
    --predicate 'subsystem == "com.example.app"'

# Filter by subsystem and category
xcrun simctl spawn booted log stream --level debug \
    --predicate 'subsystem == "com.example.app" AND category == "networking"'

# Filter by process name
xcrun simctl spawn booted log stream \
    --predicate 'process == "MyApp"'

Combining with os.Logger

Design subsystems and categories for filterability:

import os

let networkLogger = Logger(subsystem: "com.example.app", category: "networking")
let uiLogger = Logger(subsystem: "com.example.app", category: "ui")

func fetchData() async throws -> Data {
    networkLogger.debug("Starting request to /api/data")
    let (data, response) = try await URLSession.shared.data(from: url)
    networkLogger.info("Received \(data.count) bytes, status: \((response as? HTTPURLResponse)?.statusCode ?? 0)")
    return data
}

Then filter the log stream to see only networking output:

xcrun simctl spawn booted log stream --level debug \
    --predicate 'subsystem == "com.example.app" AND category == "networking"'

Compile-Time Simulator Detection

Use #if targetEnvironment(simulator) to exclude code that cannot run in the Simulator:

func registerForPush() {
    #if targetEnvironment(simulator)
    logger.info("Skipping APNs registration — running in Simulator")
    #else
    UIApplication.shared.registerForRemoteNotifications()
    #endif
}

Runtime detection via environment variables:

var isSimulator: Bool {
    ProcessInfo.processInfo.environment["SIMULATOR_DEVICE_NAME"] != nil
}

Prefer compile-time checks (#if targetEnvironment(simulator)) over runtime checks. The compiler strips excluded code entirely, preventing linker errors from unavailable symbols.

Simulator Limitations

When classifying a test as Simulator-supported or hardware-required, separate "can trigger this behavior" from "can validate real-device fidelity":

• Simulator-supported triggers/proxies: local push with simctl push, location changes, memory warnings, Face ID or Touch ID enrollment/match/nonmatch menu actions, manual iCloud sync trigger, privacy grants/resets, status bar overrides, screenshots, and video capture.
• Hardware-required validation: APNs delivery, BLE and NFC, real camera or microphone input, motion sensors, Secure Enclave, App Attest, automatic iCloud propagation/conflicts/background behavior, CPU throughput, general processing speed, networking throughput or latency, Metal shader correctness, GPU limits, memory bandwidth, frame timing, memory pressure, Jetsam, and thermal behavior.

Do not classify "iCloud sync" as a single hardware-only item. Split it explicitly:

• Simulator-supported: manual iCloud sync triggering and basic app response to sync callbacks.
• Hardware-required: automatic iCloud propagation, multiple real devices/accounts, conflict resolution, notification-triggered sync, background delivery, and account/device state differences.

Treat Simulator performance as a functional smoke signal only. When answering performance-boundary questions, explicitly name CPU throughput/general processing speed and networking throughput/latency alongside graphics, Metal shader correctness, memory bandwidth, frame timing, memory pressure, Jetsam behavior, and thermal behavior.

Use this minimum wording in release-checklist answers: "Simulator is not an accurate performance proxy for processing/CPU, graphics/Metal, memory, networking throughput/latency, Metal GPU behavior, frame timing, memory pressure/Jetsam, or thermal behavior." If a prompt only names "Metal performance," still include processing, memory, and networking in the device-verification list.

Common Mistakes

DON'T: Hardcode simulator UDIDs in scripts

UDIDs change when simulators are deleted and recreated. Hardcoded values break on other machines and CI.

# WRONG — hardcoded UDID
xcrun simctl boot "A1B2C3D4-E5F6-7890-ABCD-EF1234567890"

# CORRECT — look up by name and runtime
UDID=$(xcrun simctl list -j devices available | \
    jq -r '.devices["com.apple.CoreSimulator.SimRuntime.iOS-18-4"][] | select(.name == "iPhone 16 Pro") | .udid')
xcrun simctl boot "$UDID"

# CORRECT — use "booted" when one simulator is running
xcrun simctl install booted MyApp.app

DON'T: Install or launch on a shutdown simulator

simctl install and simctl launch require a booted device. They fail silently or with an unhelpful error on a shutdown device.

# WRONG — device is not booted
xcrun simctl install <UDID> MyApp.app  # fails

# CORRECT — boot first, then install
xcrun simctl boot <UDID>
xcrun simctl install <UDID> MyApp.app
xcrun simctl launch <UDID> com.example.MyApp

DON'T: Leave zombie simulators running in CI

Each booted simulator consumes memory and CPU. CI pipelines that create simulators without cleanup accumulate zombie devices.

# WRONG — CI script creates and boots but never cleans up
xcrun simctl create "CI Phone" "iPhone 16 Pro" "com.apple.CoreSimulator.SimRuntime.iOS-18-4"
xcrun simctl boot "$UDID"
# ... tests run, pipeline exits ...

# CORRECT — always clean up in CI teardown
cleanup() {
    xcrun simctl shutdown all
    xcrun simctl delete "$UDID"
}
trap cleanup EXIT

DON'T: Assume simctl push validates APNs delivery

simctl push bypasses the entire APNs infrastructure. It tests payload parsing and notification UI, not token registration, entitlements, or server-side delivery.

# WRONG — only testing with simctl, shipping without real device testing
xcrun simctl push booted com.example.MyApp payload.json
# "Push works!" — no, it only proves the app handles the payload

# CORRECT — use simctl for development iteration, then verify end-to-end on a real device
# 1. simctl push during development for fast iteration
# 2. Real device + APNs sandbox for integration testing before release

DON'T: Keep retrying boot on a stuck simulator

A simulator stuck in the "Booting" state will not recover by retrying boot. The underlying CoreSimulator state is corrupted.

# WRONG — retry loop on a stuck device
xcrun simctl boot "$UDID"  # "Unable to boot device in current state: Booting"
xcrun simctl boot "$UDID"  # same error, forever

# CORRECT — shut down, erase, and retry
xcrun simctl shutdown "$UDID"
xcrun simctl erase "$UDID"
xcrun simctl boot "$UDID"

# If that fails, reset CoreSimulator entirely
xcrun simctl shutdown all
xcrun simctl erase all
# Last resort: rm -rf ~/Library/Developer/CoreSimulator/Caches

Review Checklist

• [ ] Simulator devices created with explicit device type and runtime identifiers
• [ ] Scripts use booted or parsed UDID from JSON output, not hardcoded values
• [ ] Push notification payloads tested via simctl push during development
• [ ] Push notification delivery verified on a real device before release
• [ ] Location simulation tested with fixed coordinates, predefined scenarios, and custom waypoints when needed
• [ ] Privacy permissions pre-granted in CI to avoid blocking dialogs
• [ ] #if targetEnvironment(simulator) guards around APIs unavailable in Simulator
• [ ] Status bar overrides cleared after capturing screenshots
• [ ] CI pipelines shut down and delete simulators in teardown
• [ ] Log streaming configured with subsystem/category predicates for focused debugging
• [ ] App container paths used for inspecting sandboxed data during debugging

References

• Running your app in Simulator or on a device
• Downloading and installing additional Xcode components
• Testing in Simulator versus testing on hardware devices
• Testing complex hardware device scenarios in Simulator
• Simulating an external display or CarPlay
• simctl command reference: references/simctl-commands.md

simctl Command Reference

Common xcrun simctl subcommands with syntax, flags, and examples. For workflows and patterns, see the main SKILL.md.

Contents

• Device Management Commands
• App Lifecycle Commands
• Testing and Simulation Commands
• Media and IO Commands
• JSON Output Parsing
• Privacy Service Names
• Status Bar Override Flags
• Troubleshooting

Device Management Commands

Device Type and Runtime IDs

# List all device types — use the identifier column
xcrun simctl list devicetypes

# Example output line:
# iPhone 16 Pro (com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro)

# List all runtimes
xcrun simctl list runtimes

# Example output line:
# iOS 18.4 - com.apple.CoreSimulator.SimRuntime.iOS-18-4

Use the identifier strings (e.g., com.apple.CoreSimulator.SimDeviceType.iPhone-16-Pro) in create and upgrade commands.

App Lifecycle Commands

For scripts that boot a simulator before installing, prefer:

xcrun simctl bootstatus <UDID> -b
xcrun simctl install <UDID> build/Build/Products/Debug-iphonesimulator/MyApp.app

bootstatus -b safely boots if needed and waits until the simulator finishes booting. If you call simctl boot separately, follow it with xcrun simctl bootstatus <UDID> before install, launch, push, or location.

Launch Arguments and Environment

# Pass launch arguments (received as CommandLine.arguments)
xcrun simctl launch booted com.example.MyApp --reset-onboarding --debug-mode

# Override language and locale
xcrun simctl launch booted com.example.MyApp -AppleLanguages "(ja)" -AppleLocale "ja_JP"

# Set environment variables for the launched app
SIMCTL_CHILD_MY_VAR=value xcrun simctl launch booted com.example.MyApp

Use the SIMCTL_CHILD_ prefix for environment variables passed to simctl launch. Use simctl spawn for arbitrary processes inside the simulator, such as log stream, not as the default way to launch an installed app with environment.

Testing and Simulation Commands

Push Payload Format

The JSON payload mirrors the APNs payload format. The Simulator Target Bundle key is optional — when provided, the bundle ID argument can be omitted:

{
    "Simulator Target Bundle": "com.example.MyApp",
    "aps": {
        "alert": {
            "title": "Order Update",
            "subtitle": "Order #1234",
            "body": "Your order has been shipped"
        },
        "badge": 1,
        "sound": "default",
        "category": "ORDER_STATUS",
        "thread-id": "order-1234",
        "interruption-level": "time-sensitive"
    },
    "orderID": "1234"
}

The payload must be a top-level JSON object, include a valid aps dictionary, and be 4096 bytes or less. simctl push supports only application remote push notifications; it does not support VoIP, Complication, File Provider, or other push types.

Location Scenarios

The run subcommand accepts predefined scenario names, not GPX file paths:

# 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 -

# Set a fixed coordinate
xcrun simctl location booted set 37.3349,-122.0090

# Clear the simulated location
xcrun simctl location booted clear

Available scenarios include "City Run", "City Bicycle Ride", "Freeway Drive", and "Apple" (stationary at Apple Park). Use list to see all options on your system.

Use start for command-line waypoint routes. It accepts at least two latitude/longitude pairs, optional speed, and either distance- or interval-based update cadence. The command boundary matters: simctl location run accepts built-in scenario names, not GPX file paths; for custom routes already stored as GPX files, use Xcode's Debug > Simulate Location menu instead.

Media and IO Commands

Mask Options

JSON Output Parsing

Find a Booted Device UDID

xcrun simctl list -j devices booted | \
    jq -r '[.devices[][] | select(.state == "Booted")] | first | .udid'

Find a Device by Name and Runtime

RUNTIME="com.apple.CoreSimulator.SimRuntime.iOS-18-4"
xcrun simctl list -j devices available | \
    jq -r --arg rt "$RUNTIME" \
    '.devices[$rt][] | select(.name == "iPhone 16 Pro") | .udid'

List All Available Runtimes

xcrun simctl list -j runtimes | \
    jq -r '.runtimes[] | select(.isAvailable == true) | "\(.name) — \(.identifier)"'

Get Device State

xcrun simctl list -j devices | \
    jq -r --arg udid "$UDID" \
    '[.devices[][] | select(.udid == $udid)] | first | .state'

Privacy Service Names

Service names accepted by simctl privacy grant|revoke|reset:

Status Bar Override Flags

All flags for simctl status_bar <UDID> override:

App Store Screenshot Preset

xcrun simctl status_bar booted override \
    --time "9:41" \
    --batteryState charged \
    --batteryLevel 100 \
    --cellularMode active \
    --cellularBars 4 \
    --wifiMode active \
    --wifiBars 3 \
    --dataNetwork wifi \
    --operatorName ""

Troubleshooting

Stuck "Booting" State

The device shows state "Booting" and simctl boot returns "Unable to boot device in current state: Booting."

# Step 1: force shutdown
xcrun simctl shutdown <UDID>

# Step 2: erase the device
xcrun simctl erase <UDID>

# Step 3: boot again
xcrun simctl boot <UDID>

If erasing does not resolve it, delete and recreate the device. As a last resort, clear the CoreSimulator caches:

xcrun simctl shutdown all
rm -rf ~/Library/Developer/CoreSimulator/Caches

Runtime Not Installed

simctl create or simctl boot fails with "Invalid runtime" or the runtime does not appear in simctl list runtimes.

# Check what's installed
xcrun simctl list runtimes

# Download a runtime via xcodebuild
xcodebuild -downloadPlatform iOS

# Or download via Xcode > Settings > Platforms

Runtime downloads can be large (5+ GB). In CI, pre-install runtimes in the base image.

CoreSimulator Cache Corruption

Symptoms: devices fail to boot, simctl list shows stale data, or "Unable to determine simulator device status."

# Nuclear option — reset everything
xcrun simctl shutdown all
xcrun simctl erase all
rm -rf ~/Library/Developer/CoreSimulator/Caches
# Restart CoreSimulatorService
launchctl kickstart -k gui/$(id -u)/com.apple.CoreSimulator.CoreSimulatorService 2>/dev/null || true

After clearing caches, you may need to re-create custom devices. Default devices are recreated automatically by Xcode.

"Unable to boot device in current state: Shutdown"

This usually means the required runtime is not fully installed or is corrupted. Verify the runtime is available and re-download if needed:

xcrun simctl list runtimes
# If the runtime shows (unavailable), re-download it
xcodebuild -downloadPlatform iOS