Xcode Simulator App Advanced

Organizing Simulators Using the Command Line

So far, you’ve created and managed simulators using Xcode. In addition, you’ve also learned the various Simulator menu options. Now, you’ll learn to manage and use simulators from the command line.

Open Terminal. Enter the following command:

xcrun simctl --help

and press Enter.

The help option provides the list of all the subcommands available using simctl.

Simctl is a tool to help manage and programmatically interface with the simulator. You can access simctl using the xcrun command-line tool.

Now, you’ll explore several of these subcommands. Run the following:

xcrun simctl list

The list command shows the list of all the available devices and the runtimes.

It also shows the current state of the devices, whether it’s Booted or Shutdown.

Next, you’ll learn to create and launch a simulator from the command line.

Creating Simulator From the Command Line

Before creating a new simulator, delete the Demo simulator created via Xcode. Enter the following:

xcrun simctl delete Demo

The delete command identifies a simulator and deletes it. Now, create a new simulator from the command line.

Enter the following:

xcrun simctl create Demo "iPhone 12 Pro" "iOS14.2"

The create command takes in a device type and runtime and creates a simulator. This creates an iPhone 12 Pro simulator with iOS 14.2 runtime.

Now, Terminal shows the unique identifier of the new device.

Enter the following:

xcrun simctl boot Demo

The starts the Demo simulator. By default, it’s in the Shutdown state.

Now, install RayWonders using the command line. You’ll first need the app bundle. Follow these steps:

1. Open the Project navigator and select RayWonders.app, located in the Products folder.
2. Right-click and select Show in Finder.
3. Copy RayWonders to your home directory.

Open Terminal and navigate to the home directory by entering the following:

cd ~

Next, run the following:

xcrun simctl install Demo RayWonders.app

The install command installs RayWonders on the simulator. Great job!

You can even launch the app using simctl. Enter the following:

xcrun simctl launch Demo com.raywenderlich.RayWonders

The launch command takes the app bundle ID as a parameter. RayWonders launches in the Demo simulator.

Congratulations! You’ve now created, booted, installed and launched a simulator from the command line. Here are some other options you can try:

• terminate: This terminates an application using the bundle identifier.
• erase: This erases the device contents.
• uninstall: This uninstalls the application. You’ll need to specify the bundle identifier of the application.

Next, you’ll learn some cool commands that are available for your app.

Taking Screenshots

Screenshots of your app can be useful in several scenarios. For instance, you’ll need screenshots when submitting your app in AppStore.

Enter the following command:

xcrun simctl io Demo screenshot screenshot.png --type="png"

This takes a screenshot of the current screen and saves it to the file screenshot.png. In addition to a png, screenshot command supports other file formats, such as TIFF, BMP, GIF and JPEG.

A screenshot can show what your app looks like, and a picture is worth a thousand words. However, a video is worth a lot more. :]

Recording Video

You can record videos of your app using simctl. To start recording, enter the following command:

xcrun simctl io Demo recordVideo Demo.mov --codec="h264"

Interact with RayWonders on the simulator. Press Control-C in the terminal when you have finished. This saves the video in Demo.mov.

In addition, you can specify the desired codec when recording. The default codec is hevc.

The recordVideo command helps avoid using a QuickTime player to record a video of your app.

Customizing the Status Bar

Check the app’s status bar in the simulator. You can see that the battery is full, the device has the best signal and the time on the simulator is your local Mac time. What do you do if you want to override these?

Enter the following command in Terminal:

xcrun simctl status_bar Demo override \
  --dataNetwork 4g --cellularBars 2 --batteryState charging \
  --batteryLevel 25 --time 12:05

This overrides the status bar to set:

• Data network as 4G
• Cellular signal to two bars
• Battery state to charging and the battery level to 25%
• Time on the simulator to 12:05

When you do this in your own project, you can set the status bar information to whatever you want.

The status_bar command can be really handy when you want to customize the appearance of your app screenshots and videos.

When you are done, revert the status bar to the default appearance by entering the following:

xcrun simctl status_bar Demo clear

Debugging and Diagnosing

Simctl also provides several commands to help debug and diagnose issues.

Go back to Terminal, and enter the following:

xcrun simctl get_app_container Demo com.raywenderlich.RayWonders

get_app_container prints the app bundle’s path.

You can inspect the data within the app container using this path. In addition, your simulator logs can be really useful when debugging issues.

Now, type the following in Terminal:

xcrun simctl spawn Demo log stream

This starts streaming all the logs from the Demo simulator.

However, this can be too much data to inspect. Press Control-C to stop the stream.

Try the following:

xcrun simctl spawn Demo log stream | grep com.raywenderlich.RayWonders

This filters the logs and displays only those from RayWonders.

As you interact with the app, you’ll see more logs displayed in the terminal. These logs can be extremely useful when filing a bug or providing feedback to Apple.

Type the following:

xcrun simctl diagnose

The diagnose command collects a bunch of data, including logs and crashes. It also generates files that can help Apple debug issues. By default, the collected logs are for the booted device. By specifying the UDID of a device, you can constrain the collection of logs to that particular device.

You’ve now become a simulator command line expert! You can take it a step further by automating common actions using Bash scripts.

Automating Using a Bash Script

Now, you’ll create a script to clone a simulator and launch RayWonders in a different locale.

First, open Terminal, and enter the following:

touch sim_utility.sh

This creates a new file with the name sim_utility. The .sh extension denotes that it’s a shell script.

Next, run:

chmod +x sim_utility.sh

This makes the sim_utility.sh executable so you can run it.

Open sim_utility.sh in an editor, and add the following:

#!/bin/bash

#1
COMMAND="$1"
SIMULATOR_NAME="$2"

#2
get_id_of_simulator() {
  #TODO
}

get_status_of_simulator() {
  #TODO
}

launch() {
  #TODO
}

#3
case $COMMAND in
"launch") launch "$3" "$4" "$5" ;;
*)
  launch_help
  exit 1
  ;;
esac

Here’s what’s going on:

1. The script takes in a command name and a simulator name as the command line parameters.
2. get_id_of_simulator, get_status_of_simulator and launch are empty stubs that you’ll implement next.
3. The script currently supports one command named launch. The launch takes three additional parameters, which you’ll implement soon.

In get_id_of_simulator, replace #TODO with the following:

xcrun simctl list | grep "$SIMULATOR_NAME" | \
awk 'match($0, /\(([-0-9A-F]+)\)/) {print substr( $0, RSTART + 1, RLENGTH-2 )}'

get_id_of_simulator searches the list of a simulators to match the name specified as a parameter. If it finds a match, the substring operation gets the unique identifier of the simulator.

In the get_status_of_simulator method, replace #TODO with the following:

xcrun simctl list | grep "$SIMULATOR_NAME" | \
awk 'match($0, /\(([a-zA-Z]+)\)/) {print substr( $0, RSTART + 1, RLENGTH - 2 )}'

get_status_of_simulator searches for a simulator with a matching name in the list of devices. If it finds a match, it gets the status of the simulator — booted or shutdown. You’ll use these in the launch.