RY 's Blog

## iOS Simulator from the Command Line

2020-02-05

xcrun simctl is command utils to control iOS simulator, just like adb for Android. Sometimes, in CI server script, We need these simulator-integration command to interact with simulators and run test cases.

If we run xcrun simctl help, here are some subcommands. When successful, most of these commands exit with 0; when failed, most exit with a non-zero number.

Just see I can do a lot of things with these command. If wanting to know more about a specific subcommand, we can use xcrun simctl help [subcommand] to seek help. Like, xcrun simctl help boot

### Simulator info

use xcrun simctl list to see all the simulator information. We can get a list of device types, a list of info of runtime names, a list of device names.

Use xcrun simctl list device to see the list of device info. Or use a device name to get paired devices’ info, like name, uuid, and status. For example,

### Get device environment variable

xcrun simctl getenv is for printing an environment variable from a running device.

Take the follow command as an example, the SIMULATOR_UDID environment variable contains the UDID of the simulated device. But it doesn’t work for physical device.

We can add more environment variables by ourselves in schema for debugging use.

Launch Arguments & Environment Variables

### Create a custom simulator

xcrun simctl create <name> <device type> <runtime>
For example, if I would like to create a iPhone 11 Pro Max with iOS 13.3, I can use the follow command.

The uuid of the new simulator is BE9A72F0-5793-447B-BEC4-63A73242BED5, which is output in standard out. And errors comes to standard error.

Tips: you should use available runtime, or you will get an error of invalid runtime: xxx.

If in shell scrip, we can capture the new device’s name using environment variable:

Another way to create a simulator using GUI is to go to Window -> Devices and Simulators

### Boot a simulator

Boot a device using \$uuid

xcrun simctl boot BE9A72F0-5793-447B-BEC4-63A73242BED5

Use simctl shutdown <device> to shutdown a device.

### Install/Uninstall app

xcrun simctl install <device> <path>. We use this command to install an app on a device.

booted is the alias name of the booted device. We can also use uuid of a device.

use simctl uninstall <device> <app bundle identifier> to uninstall an app. like
xcrun simctl uninstall booted com.rong.lan.CubeTransitionAnimationDemo

### Launch

xcrun simctl launch <device> <bundle> <arguments>.

Launch command is used to launch a application in your simulator device.

com.apple.example is bundle id of the application.

If we use --console-pty, launch command will connect the standard output and error of the application to the terminal line.

Use xcrun simctl terminate <device> <bundle> to terminate an application by identifier on a device.

### Container Path

xcrun simctl simctl get_app_container <device> <app bundle identifier> [<container>] command is used to get the path of the installed app’s container.

For example

### Spawn

Spawn command will pause xspawn, a process inside the simulator environment.

Here, we use defaults utils, because we already have a booted device BE9A72F0-5793-447B-BEC4-63A73242BED5, we don’t have to specify the device.

com.example.app is bundle id of my application. We reset ResetDatabase to YES.
This is a handy way to change the user defaults for the application before its running.

### Log Stream

spwan command would work with log stream utility. We can pass a predicate and filter the log output. Here the predicate is senderImagePath CONTAINS "nsurlsessiond". We can debug something wrong with URL session.

Also, we can use different predicates to filter what we want.

### Dignose

In a auto-test system, if having some kind of issue, by using this command, you can not only collect logs on disk but also capture ephemeral logging and dump system state.

### Clone

Clone is a very powerful command. See details in wwdc2019/418.

xcrun simctl clone <device> <clone name>. You can copy your custom device using this command.

Two new devices are created with the same contents.

1. Create a .apns file, ExamplePush.apns

valid Apple Push Notification values. Noted that the Target Bundle should be the same as the bundle identifier

1. Drag and drop an APNs file onto the target simulator.

The file must be a JSON file with a valid Apple Push Notification Service payload, including the “aps” key. It must also contain a top-level “Simulator Target Bundle” with a string value matching the target application‘s bundle identifier. – https://stackoverflow.com/a/60085404/4026902

Or, we use command lines.

### Privacy and Permissions

These commands, introduced in Xcode 11.4, could be very useful when you are developing some features and have to test the permissions.

For example,

and use revoke to revoke the permissions.

### StatsBar override

Usage: simctl status_bar <device> [list | clear | override <override arguments>]

It seems it can support a lot of overrides variables in status bar. But I have figure out the scenarios to use them.

and use clear option to clear all the settings.

https://developer.apple.com/videos/play/wwdc2020/10647/

### Record Video

We can run xcrun simctl io --help to see more.

This command records the content of the screen of the current booted simulator, and save it to the video.mp4 file. To stop recording, we have to use ctl+c in the terminal.

recordVideo cannot save recorded video output into a file that already exists unless we use -f flag to override the existing file.

• By default, codec type is hevc.
• Ignore the mask when the mask is rendered black because of compatibility issues.

And we can also capture the out of the external display of the simulator.