Creating iOS Simulators for End-to-End Automation Tests

Previously, we have discussed how to create a custom Android Emulator. Now I would like to address the other side of the coin: how to create a custom iOS Simulator. Testing your iOS app on various simulator configurations is a necessity during the pre-release process. It provides assurance that your app’s functionality and UI layout works across a variety of device types. Furthermore, automating the iOS simulator creation gives you the ability to create a cost-effective virtual device lab in your own infrastructure.

In this guide we will first walkthrough Xcode’s GUI tool for creating a standard Simulator. Then we will explore a tool called simctl and how its CLI can be used to create and a launch a custom iOS Simulator.

Creating a standard Simulator

To open a standard Simulator, you will first need Xcode installed. Open Xcode and click on “Xcode” in the menu bar. Hover over “Open Developer Tool” and then select the “Simulator” option. You will see an iOS Simulator boot up on your screen.

To create another simulator, you will need to click on “File” > “New Simulator…” in the menu bar. This will open another window with the New Simulator GUI. This GUI will allow you enter a name and then select the Device Type and OS Version for the new the Simulator that you want to create.

New Simulator GUI Wizard

You can then launch it by clicking on “File” > “Open Simulator” > OS Version > Name of the simulator you entered. Usually, it takes about a few minutes for the simulator to start upon first creation.

Exploring simctl

Apple has a simctl tool for interacting with iOS simulators from the terminal. It resides in /Applications/Xcode.app/Contents/Developer/usr/bin/simctl and is accessible in your PATH after Xcode is installed. This tool has a lot of options that can be viewed using the following command:

$ xcrun simctl help

simctl options

I will go over the subcommands that are required for our objective and offer a few examples.

Listing Options

We can get a listing of all the available device target options by running:

$ xcrun simctl list

The output is divided into the four sections:

• Device Types: The devices Apple has created
• Runtimes: The iOS/tvOS/watchOS versions
• Devices: Configured targets that are a combination of a Device Type + Runtime
• Device Pairs: Apple Watch & iPhone device pairs

In the Devices section note that each option has an associated UDID. You’ll use this unique identifier in other simctl subcommands that take a device parameter.

We can can also list only specific sections by adding the section name after the list command.

# List Device Types
$ xcrun simctl list devicetypes
# List Simulator Runtimes
$ xcrun simctl list runtimes
# List Devices
$ xcrun simctl list devices
# List Device Pairs
$ xcrun simctl list pairs

Creating a new Simulator

To create a Simulator, we need to provide three things:

• An arbitrary name
• Device Type
• Runtime

You can then provide this information to the create sub-command to create the desired Simulator. For example:

$ xcrun simctl create "Example Simulator" com.apple.CoreSimulator.SimDeviceType.iPhone-12 com.apple.CoreSimulator.SimRuntime.iOS-14-3

After executing, this command will print the UDID of the new simulator that was created.

Launching a Simulator

To open this Simulator, we will use the following command and provide the UDID from the previous step. For example:

$ xcrun simctl boot 26F892AB-AA36-45FD-95FA-0DD957A16C29

Note: If you want to see which Simulators are currently running on your machine, you can grep for the status of “Booted” from the list command.

$ xcrun simctl list | grep Booted

Packaging into a shell script

To synthesize what we have covered so far, we will write a short shell script that could be used in a CI/CD pipeline. The script below creates and launches the Simulator with name “my-sim”.

#! /bin/zsh  
SIMULATOR_NAME="my-sim"
  
# Create Simulator
SIMULATOR_UDID=`xcrun simctl create "$SIMULATOR_NAME" com.apple.CoreSimulator.SimDeviceType.iPhone-12 com.apple.CoreSimulator.SimRuntime.iOS-14-3`
 
# Run Simulator
xcrun simctl boot $SIMULATOR_UDID

Additional Helpful Commands

I’d like to also share examples of other helpful commands that you can utilize from a shell script.

Install your .app file

You can install your .app Simulator build using:

$ xcrun simctl install <UDID> <PATH-TO-APP>

Launch an existing app

We can launch an app from the Simulator using:

$ xcrun simctl launch <UDID> <BUNDLE-ID>

For example, if you completed “Building and testing native mobile apps with React Native and WebdriverIO” this is how you could launch the stock price app:

$ xcrun simctl launch <UDID> com.nathankrishnan.stockprice

Remove data from a Simulator

If you need to test your app on a clean Simulator target, you can run:

# Shutdown the Simulator
$ xcrun simctl shutdown <UDID>
# Erase data contents from the Simulator
$ xcrun simctl erase <UDID>

Note: The order is important here. You can’t remove data from the Simulator without shutting it down first.

Opening a URL

We can open a URL in Mobile Safari using:

$ simctl openurl <UDID> <URL>

For example, if we wanted to launch https://www.tauk.com we could run:

$ xcrun simctl openurl <UDID> "https://www.tauk.com"

Add Photos or Videos onto the Simulator

You can push photos or videos to the Simulator by running:

$ simctl addmedia <UDID> <PATH-TO-FILE>

Conclusion

The command line tool simctl can be used for creating and interfacing with iOS Simulators. We can leverage the simctl operations to create virtual device targets for automation tests. Furthermore, we can package its commands into a shell script to facilitate automation test pipelines for use in CI/CD.