While developing iOS apps, simulators are the best friends of developers. It’s the quick and easy way to test app while development as we can interact with iOS simulators using GUI. Apple’s documentation on getting started in the simulator is awesome and we can learn almost everything about controlling simulators from using graphical user interface.

Although simulators are easy to use with GUI, it’s a bit painful to script simulator interactions to run on Continuous Integration server. Fortunately, Apple has nice command line utility called “simctl”.

In this post, let’s see how to use ‘simctl’ to interact with iOS simulators. We will cover following

• Creating, Deleting and Booting Simulators
• Adding photos and video to simulators
• Installing/Uninstalling, launching/Terminating app inside simulator
• Capturing screenshot and record video of simulator
• Collecting the simulator logs and other tricks

simctl

Apple has ‘simctl’ binary to interact with iOS simulators from the command line. It’s very similar to the adb for Android. Again it’s another utility poorly documented by Apple but we can find binary at /Applications/Xcode.app/Contents/Developer/usr/bin/simctl  and we can use it with xcrun utility. We can access all the available options using the help command

We can perform various actions on iOS simulator using ‘simctl’ from creating new simulator, erasing simulator, installing app inside the simulator, add photo/video to the simulator and may more. Let’s look into few of them in details.

Listing all available simulators

We can easily list all the available simulators using command

$ xcrun simctl list

This command will list all the available simulators with the runtime. It will also show ‘booted’ simulator if it’s running already.

CRUD operations on Simulators

We can create, erase, delete, boot, shutdown and upgrade simulators using simctl.

Create

We can easily create new simulator called ‘My-iPhone7″ on top of existing iPhone7 (iOS 10.3) simulator using command

We can see that newly created simulator using list option and we have UUID for the simulator ‘C86A559A-1F50-40D1-8D84-954EDFBBCE18′  

Shutdown/Erase/Boot

As we have already seen that, there is another simulator already booted, let’s shut it down and erase its content. The order is important here, we can’t erase simulator in the booted state, we need to shut down first then erase.

Boot

Now let’s boot the newly created simulator using new UUID

Now that, we have learned how to shutdown, boot and erase simulator. Let open any simulator by using

You can see that simulator is booting.

Add Photo/Video to Simulator

An iOS simulator by default has 5 images but we can add more images or video using simctl addmedia functionality.  Let’s add one photo(png) and on video(gif) inside our simulator which is kept on the desktop.

Now, the simulator will have another photo. Similarly, we can add video as well.

Install/Uninstall app inside Simulator

We can easily install our app inside simulator from the command line if we already have a path to .app  file from derived data. Let’s create new single view app in Xcode and name it “CLI” and save it on the desktop. We need to build the app using xcodebuild to get CLI.app in the derived data.

Now, we will get the CLI.app inside derived data, in my case it’s inside  /Users/shashi/Library/Developer/Xcode/DerivedData/CLI-dxasphjukowuptcqxzbmyaqgpbqp/Build/Products/Debug-iphoneos/CLI.app  directory.

We can install our CLI.app inside simulator using

Watch the GIF below where we are installing CLI.app

Similarly, we can uninstall our iOS app from simulator easily. We need to know the bundle identifier of our app. In my case it’s test.CLI  we can uninstall app using

Launch/Terminator app inside Simulator

Similar to installation, we can launch and terminate an app using command line using simctl. We have to make sure app is installed before we launch.

We can see that app is launched, we can then terminate app using

Screenshot and Video Recording of Simulator

In Xcode 8.2, Apple introduced this really nice feature of capturing the screenshot and recording video of the simulator. Now it’s easy to capture a screenshot of the simulator. We can capture current state of simulator using

This will save the screenshot of the simulator in the current working directory with file screen.png

Similarly, we can record video of simulator while using app and save it on disk using

This will save video of the simulator to news.mov file which can be played using Quick Time player or similar.

Collecting Simulator Logs

Sometimes it would be helpful to print the simulator logs as console output. We can easily determine the activity of the simulator by reading the logs. Let’s print the logs of simulators

$ xcrun simctl spawn booted log stream --level=debug

we can also filter the log output if you looking for logs of the particular app

Miscellaneous Bulk Actions

There are a couple of dirty hacks which might be useful as well in some cases when you don’t want so many simulators.

Erase all Simulators

We can erase all the simulators using the simple command

Delete all the Simulators

The following script will delete all your simulators so beware of the impact and use when really needed.

Find  Simulator by Name Regex

Sometimes we might need to find the simulator by name and perform an action on that UUID. We can find that UUID using the name and then erase/delete/boot simulator. Let’s erase simulator containing name “Shashi”

Conclusion

Using simctl utility we can programmatically interact with iOS simulators and script the setup for test execution on CI servers.  What’s your experience with ‘simctl’, comment below