Manages iOS Simulator devices and app tests with xcrun simctl: lifecycle, install/launch, push and location simulation, privacy permissions, deep links, status-bar overrides, screenshots/video, log streaming, app containers, and targetEnvironment(simulator). Use when scripting Simulator workflows, d

iOS Simulator Load [the simctl command reference](references/simctl commands.md) when you need complete command tables, JSON parsing, privacy/status bar values, Logger filter setup, or boot recovery commands. 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 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 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. Use the returned UDID for subsequent commands. Boot, Shutdown, Erase, Delete Use booted as a UDID shorthand when exactly one simulator is running: If multiple simulators are booted, booted picks one of them non deterministically. Prefer explicit UDIDs when running parallel simulators. In scripts and CI, xcrun simctl bootstatus <UDID b is the canonical boot and readiness gate before install, launch, push, or location commands. App Install and Launch Installing an App The path must point to a .app directory built for the simulator architecture, not a .ipa file. Launching and Terminating console is useful for debugging — it shows print() and os log output directly in the terminal. App Container Paths Testing Workflows Push Notification Simulation Create a JSON payload file: Send it to the Simulator: This tests local payload handling and notification UI, not APNs delivery. Location Simulation 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 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 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 Use status bar overrides to produce consistent App Store screenshots. Always clear overrides after capturing to avoid confusing other testing. Screenshot and Video Recording 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 Load [Logger and Filtered Streaming](references/simctl commands.md logger and filtered streaming) when defining Logger subsystems/categories and matching log stream predicates. Compile Time Simulator Detection Use if targetEnvironment(simulator) to exclude code that cannot run in the Simulator: Runtime detection via environment variables: Prefer compile time checks ( if targetEnvironment(simulator) ) over runtime checks. The compiler strips excluded code entirely, preventing linker errors from unavailable symbols. Simulator Limitations Use this table as the authoritative classification. A supported trigger or proxy does not establish real device fidelity. Capability Simulator Support APNs push delivery No — use simctl push for local simulation Performance fidelity Relative only — Simulator is not accurate for CPU/processing performance, networking speed, graphics/Metal, memory bandwidth, frame timing, memory pressure, Jetsam, shader correctness, or thermal behavior; verify performance sensitive work on hardware Metal GPU family parity Partial — Simulator uses the host Mac GPU, not the device GPU; some shaders and limits differ Camera hardware No — use photo library injection or mock AVCaptureSession Audio input / microphone No general app audio input; Siri can be activated from Simulator menus Secure Enclave No — kSecAttrTokenIDSecureEnclave operations fail App Attest (DCAppAttestService) No — isSupported returns false DockKit motor control No — no physical accessory connection Accelerometer / Gyroscope No motion sensor support; use real devices for motion dependent behavior Barometer No NFC (Core NFC) No Bluetooth (Core Bluetooth) No — use a real device for BLE testing CarPlay display simulation Supported through Simulator's external display/CarPlay option; still verify in vehicle or device setups Face ID / Touch ID hardware No hardware — use Features Face ID / Touch ID menu in Simulator Memory warnings, location changes, manual iCloud sync trigger Supported through Simulator menus or simctl ; manual sync can test app callback handling Automatic iCloud propagation and conflicts Hardware required for real accounts/devices, notification triggered sync, background delivery, conflicts, and account/device state differences Cellular network conditions No — use Network Link Conditioner on Mac 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. 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. 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. 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. 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](https://sosumi.ai/documentation/xcode/running your app in simulator or on a device) [Downloading and installing additional Xcode components](https://sosumi.ai/documentation/xcode/installing additional simulator runtimes) [Testing in Simulator versus testing on hardware devices](https://sosumi.ai/documentation/xcode/testing in simulator versus testing on hardware devices) [Testing complex hardware device scenarios in Simulator](https://sosumi.ai/documentation/xcode/testing complex hardware device scenarios in simulator) [Simulating an external display or CarPlay](https://sosumi.ai/documentation/xcode/simulating an external display or carplay) simctl command reference: [references/simctl commands.md](references/simctl commands.md)

ios-simulator