Swift Simctl

This is a small tool (SimctlCLI) and library (Simctl), written in Swift, to automate xcrun simctl commands for Simulator in unit and UI tests.

It enables, among other things, reliable fully automated testing of Push Notifications with dynamic content, driven by a UI Test you control.

🚧 Architecture

Swift Simctl is made of two parts. SimctlCLI and Simctl.

Simctl is a Swift library that can be added to your project's test bundles. It provides an interface to commands that are otherwise only available via xcrun simctl from within your test code. To enable calling these commands Simctl communicates over a local network connection to SimctlCLI.

SimctlCLI is a small command line tool that starts a local server, listens to requests from Simctl (the client library) and executes xcrun simctl commands.

⌨ Available Commands

The following commands will be available in code in your (test) targets:

• Send push notifications with custom payload
• Grant or revoke privacy permissions (i.e. camera, photos ...)
• Set the device UI appearance to light or dark mode
• Set status bar overrides (i.e. data network, time ...)
• Uninstall app by bundle id
• Terminate app by bundle id
• Rename device
• Trigger iCloud Sync
• Open URLs including registered URL schemes
• Erase the contents and settings of the simulator
• Get app container

❔ Why would you (not) use this

➕ Pro

• Closed system (Mac with Xcode + Simulator)
• No external dependencies on systems like APNS
• No custom test code bloating your code base (AppDelegate) unnecessarily
• Push notifications can be simulated properly and the normal app cycle is preserved
• Runs on CI machines
• Your app stays a black box and does not need to be modified

➖ Contra

• Needs a little configuration in your Xcode project
• Only available for Xcode 11.4+

For specific usage please refer to the example projects Swift Simctl Package Example

🚀 Getting Started

These instructions will get your copy of the project up and running on your machine.

📋 Prerequisites

• Xcode 11.4 and higher.
• Swift Package Manager (SPM)

💻 Usage

📦 Swift Package

To use Swift Simctl in your Xcode project add the package:

1. Xcode > File > Swift Packages > Add Package Dependency...
2. Choose Package Repository > Search: SwiftSimctl or find https://github.com/ctreffs/SwiftSimctl.git
3. Select SwiftSimctl package > Next
4. Do not forget to add the dependency to your (test) target
5. Use import Simctl to access the library in your (test) target.

Running the server alongside your tests

Make sure that for the duration of your test run SimctlCLI runs on your host machine. To automate that with Xcode itself use the following snippets as pre and post action of your test target.

Your Scheme > Test > Pre-Actions > Run Script

#!/bin/bash
killall SimctlCLI # cleaning up hanging servers
set -e # fail fast
# start the server non-blocking from the checked out package
${BUILD_ROOT}/../../SourcePackages/checkouts/SwiftSimctl/bin/SimctlCLI start-server > /dev/null 2>&1 &

Your Scheme > Test > Post-Actions > Run Script

#!/bin/bash
set -e
killall SimctlCLI

📝 Code Example Swift Package

Please refer to the example project for an in depth code example https://github.com/ctreffs/SwiftSimctlExample

💭 Port and settings

The default port used by the server is 8080.
If you need to use another port you need to provide it via the --port flag when calling SimctlCLI and adjust the client port accordingly when setting up your test in code.
Use SimctlCLI --help to get help regarding this and other server configuration settings.

🙏 Kudos

Swift Simctl would not be possible without these awesome libraries:

• ShellOut - easy command line invocations
• Swifter - a tiny http server

💁 How to contribute

If you want to contribute please see the CONTRIBUTION GUIDE first.

Before commiting code please ensure to run:

• make precommit

This project is currently maintained by @ctreffs.
See also the list of contributors who participated in this project.

🔏 Licenses

This project is licensed under the MIT License - see the LICENSE file for details.