iPhone

Managing The Xcode Simulator Programmatically

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/

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.