The iOS Simulator is a great way to test watchOS, tvOS, and iOS apps while you’re writing them. The easiest way to work with the simulator is through Xcode. But you can also use simctl for interacting with it, helpful in automating QA operations when possible. The simctl binary is located at /Applications/Xcode.app/Contents/Developer/usr/bin/simctl and typically accessed as a verb from the /usr/bin/xcrun command.
First let’s list all the simulators, done using the list command, called by simply running xcrun followed by simctl for the type of operation to be run and then the list command:
/usr/bin/xcrun simctl list
The output shows a lot of device types, runtimes, and devices, most of which should show as disconnected or shutdown:
== Device Types ==
== Device Types ==
iPhone 4s (com.apple.CoreSimulator.SimDeviceType.iPhone-4s)
iPhone 5 (com.apple.CoreSimulator.SimDeviceType.iPhone-5)
iPhone 5s (com.apple.CoreSimulator.SimDeviceType.iPhone-5s)
iPhone 6 (com.apple.CoreSimulator.SimDeviceType.iPhone-6)
iPhone 6 Plus (com.apple.CoreSimulator.SimDeviceType.iPhone-6-Plus)
iPhone 6s (com.apple.CoreSimulator.SimDeviceType.iPhone-6s)
iPhone 6s Plus (com.apple.CoreSimulator.SimDeviceType.iPhone-6s-Plus)
iPhone 7 (com.apple.CoreSimulator.SimDeviceType.iPhone-7)
iPhone 7 Plus (com.apple.CoreSimulator.SimDeviceType.iPhone-7-Plus)
iPhone 8 (com.apple.CoreSimulator.SimDeviceType.iPhone-8)
iPhone 8 Plus (com.apple.CoreSimulator.SimDeviceType.iPhone-8-Plus)
iPhone SE (com.apple.CoreSimulator.SimDeviceType.iPhone-SE)
iPhone X (com.apple.CoreSimulator.SimDeviceType.iPhone-X)
iPhone Xs (com.apple.CoreSimulator.SimDeviceType.iPhone-XS)
iPhone Xs Max (com.apple.CoreSimulator.SimDeviceType.iPhone-XS-Max)
iPhone Xʀ (com.apple.CoreSimulator.SimDeviceType.iPhone-XR)
iPad mini (5th generation) (com.apple.CoreSimulator.SimDeviceType.iPad-mini–5th-generation-)
iPad Air (3rd generation) (com.apple.CoreSimulator.SimDeviceType.iPad-Air–3rd-generation-)
iPad 2 (com.apple.CoreSimulator.SimDeviceType.iPad-2)
iPad Retina (com.apple.CoreSimulator.SimDeviceType.iPad-Retina)
iPad Air (com.apple.CoreSimulator.SimDeviceType.iPad-Air)
iPad mini 2 (com.apple.CoreSimulator.SimDeviceType.iPad-mini-2)
iPad mini 3 (com.apple.CoreSimulator.SimDeviceType.iPad-mini-3)
iPad mini 4 (com.apple.CoreSimulator.SimDeviceType.iPad-mini-4)
iPad Air 2 (com.apple.CoreSimulator.SimDeviceType.iPad-Air-2)
iPad (5th generation) (com.apple.CoreSimulator.SimDeviceType.iPad–5th-generation-)
iPad Pro (9.7-inch) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro–9-7-inch-)
iPad Pro (12.9-inch) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro)
iPad Pro (12.9-inch) (2nd generation) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro–12-9-inch—2nd-generation-)
iPad Pro (10.5-inch) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro–10-5-inch-)
iPad (6th generation) (com.apple.CoreSimulator.SimDeviceType.iPad–6th-generation-)
iPad Pro (11-inch) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro–11-inch-)
iPad Pro (12.9-inch) (3rd generation) (com.apple.CoreSimulator.SimDeviceType.iPad-Pro–12-9-inch—3rd-generation-)
Apple TV (com.apple.CoreSimulator.SimDeviceType.Apple-TV-1080p)
Apple TV 4K (com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-4K)
Apple TV 4K (at 1080p) (com.apple.CoreSimulator.SimDeviceType.Apple-TV-4K-1080p)
Apple Watch – 38mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-38mm)
Apple Watch – 42mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-42mm)
Apple Watch Series 2 – 38mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-Series-2-38mm)
Apple Watch Series 2 – 42mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-Series-2-42mm)
Apple Watch Series 3 – 38mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-Series-3-38mm)
Apple Watch Series 3 – 42mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-Series-3-42mm)
Apple Watch Series 4 – 40mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-Series-4-40mm)
Apple Watch Series 4 – 44mm (com.apple.CoreSimulator.SimDeviceType.Apple-Watch-Series-4-44mm)
== Runtimes ==
iOS 12.2 (12.2 – 16E226) – com.apple.CoreSimulator.SimRuntime.iOS-12-2
tvOS 12.2 (12.2 – 16L225) – com.apple.CoreSimulator.SimRuntime.tvOS-12-2
watchOS 5.2 (5.2 – 16T224) – com.apple.CoreSimulator.SimRuntime.watchOS-5-2
== Devices ==
— iOS 12.2 —
iPhone 5s (4A2CC670-55EF-4B36-896F-EC2009EDEC07) (Shutdown)
iPhone 6 (937105ED-AEF1-4487-B406-1795D9AD9243) (Shutdown)
iPhone 6 Plus (E4031984-D79E-4888-A104-0C6DA73EB67F) (Shutdown)
iPhone 6s (EA859DD2-D934-4CB1-B2D5-055F1DF93FB9) (Shutdown)
iPhone 6s Plus (CFFD27D8-4FEE-4632-B3BB-8133DBF74925) (Shutdown)
iPhone 7 (66BE2C4D-CB66-4618-A95D-BF239C569965) (Shutdown)
iPhone 7 Plus (3C6B97F3-AF19-49A9-B400-09A5CBCCB3D6) (Shutdown)
iPhone 8 (2D18B685-A642-44E5-BF8E-6D09AB478B0F) (Shutdown)
iPhone 8 Plus (BF652604-8F18-457C-B111-E951E8B55947) (Shutdown)
iPhone SE (384E1A51-7354-4FAC-A1A8-CB2B9CC5D1CF) (Shutdown)
iPhone X (98DD2AEC-4566-4896-83E5-E0B8603FFE9E) (Shutdown)
iPhone Xs (02A90E87-B2C4-44FE-9477-DD9455D7CB0C) (Shutdown)
iPhone Xs Max (79F42764-5020-41EA-87C3-55C541A790F5) (Shutdown)
iPhone Xʀ (AD6FD253-20A7-432C-8C22-5070489E787E) (Shutdown)
iPad Air (3rd generation) (DAB405D3-C1FD-47ED-B4FE-F0E1857A2862) (Shutdown)
iPad Air (3216E338-D522-43C7-9484-D7AEA081E926) (Shutdown)
iPad Air 2 (6B0BCC75-0ED6-4FC9-94C5-48A3466B79AD) (Shutdown)
iPad (5th generation) (24313239-A853-46EB-B5A3-0DD8A86080F2) (Shutdown)
iPad Pro (9.7-inch) (8E2BEE13-D726-4CF5-8388-0913B87495F1) (Shutdown)
iPad Pro (12.9-inch) (9493C54B-D61E-4D42-8952-A89C2CCF2FDD) (Shutdown)
iPad Pro (12.9-inch) (2nd generation) (5D978189-856D-4598-8C09-876BD832C71F) (Shutdown)
iPad Pro (10.5-inch) (2BF88E18-8C89-4515-A486-DC72C7A8629E) (Shutdown)
iPad (6th generation) (016DAA95-D917-4CD9-9A54-700D01BAF1AE) (Shutdown)
iPad Pro (11-inch) (307BEEDD-8652-4438-944B-CB423A26CC9E) (Shutdown)
iPad Pro (12.9-inch) (3rd generation) (D893291C-F214-4B43-A54F-3AB95A5442ED) (Shutdown)
— tvOS 12.2 —
Apple TV (1562B2B3-F403-4C99-8026-20AA51C8716B) (Shutdown)
Apple TV 4K (6C5CC68C-4C01-4097-91B8-A503B465F961) (Shutdown)
Apple TV 4K (at 1080p) (B8DCEFC3-F5BC-455D-B8B7-BAE7A48BE032) (Shutdown)
— watchOS 5.2 —
Apple Watch Series 2 – 38mm (06938C62-9757-4F5E-913F-F9639D8AFF9C) (Shutdown)
Apple Watch Series 2 – 42mm (BBA6DFC3-BC5A-494F-AFF4-E2B1331AFC69) (Shutdown)
Apple Watch Series 3 – 38mm (2D70BA7B-66BF-43E1-9F80-20EEFF588BB5) (Shutdown)
Apple Watch Series 3 – 42mm (F0E4E11E-639C-4F45-974A-2AAC684F1411) (Shutdown)
Apple Watch Series 4 – 40mm (B0CC419F-220F-46E1-B827-B512B08552B6) (Shutdown)
Apple Watch Series 4 – 44mm (7DAE1296-C9FF-4759-A066-1BA42A259853) (Shutdown)
== Device Pairs ==
620743A8-FD31-408C-AEBF-8D0F0849BD9D (active, disconnected)
Watch: Apple Watch Series 4 – 40mm (B0CC419F-220F-46E1-B827-B512B08552B6) (Shutdown)
Phone: iPhone Xs (02A90E87-B2C4-44FE-9477-DD9455D7CB0C) (Shutdown)
20E13C7F-3788-4DA5-962A-FF1389CDDA12 (active, disconnected)
Watch: Apple Watch Series 4 – 44mm (7DAE1296-C9FF-4759-A066-1BA42A259853) (Shutdown)
Phone: iPhone Xs Max (79F42764-5020-41EA-87C3-55C541A790F5) (Shutdown)
Next, let’s create a fresh new spiffy simulator called testing_iPhone7. To do so we’ll
/usr/bin/xcrun simctl create testing_iPhone7 com.apple.CoreSimulator.SimDeviceType.iPhone-7 com.apple.CoreSimulator.SimRuntime.iOS-12-2
The output includes a UUID such as the following. That can then be used to track further interactions with the simulation:
E6D4C2B8-0601-4557-99DA-B6B8251D534D
The most common tasks would be booting, shutting down, erasing, and opening simulations. First let’s boot it up:
/usr/bin/xcrun simctl boot E6D4C2B8-0601-4557-99DA-B6B8251D534D
To shut that same simulator down use the shutdown verb:
/usr/bin/xcrun simctl shutdown E6D4C2B8-0601-4557-99DA-B6B8251D534D
Neither of these commands provide any output on success, but do error on failure. Once you’ve run tests, I like to erase my simulator and start fresh. To do so, simply use the erase command:
/usr/bin/xcrun simctl erase E6D4C2B8-0601-4557-99DA-B6B8251D534D
To open the simulator you loaded, you can use the open Simulator.app :
open /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app/
For more information on using simctl subcommands, use the help subcommand:
/usr/bin/xcrun simctl help
Notice there are a lot of verbs, which I’ll cover further in later articles:
create Create a new device.
clone Clone an existing device.
upgrade Upgrade a device to a newer runtime.
delete Delete a device or all unavailable devices.
pair Create a new watch and phone pair.
unpair Unpair a watch and phone pair.
pair_activate Set a given pair as active.
erase Erase a device’s contents and settings.
boot Boot a device.
shutdown Shutdown a device.
rename Rename a device.
getenv Print an environment variable from a running device.
openurl Open a URL in a device.
addmedia Add photos, live photos, videos, or contacts to the library of a device.
install Install an app on a device.
uninstall Uninstall an app from a device.
get_app_container Print the path of the installed app’s container
launch Launch an application by identifier on a device.
terminate Terminate an application by identifier on a device.
spawn Spawn a process by executing a given executable on a device.
list List available devices, device types, runtimes, or device pairs.
icloud_sync Trigger iCloud sync on a device.
pbsync Sync the pasteboard content from one pasteboard to another.
pbcopy Copy standard input onto the device pasteboard.
pbpaste Print the contents of the device’s pasteboard to standard output.
help Prints the usage for a given subcommand.
io Set up a device IO operation.
diagnose Collect diagnostic information and logs.
logverbose enable or disable verbose logging for a device
Next up, we’ll look at performing tasks in the Simulator in the next article on regression testing with the Simulator app.