Swiftpack.co - ctreffs/SwiftSimctl as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
ctreffs/SwiftSimctl 0.3.0
Swift client-server tool to call xcrun simctl from your simulator. Automate push notification testing!
⭐️ 43
πŸ•“ 2 weeks ago
iOS macOS tvOS
.package(url: "https://github.com/ctreffs/SwiftSimctl.git", from: "0.3.0")

Swift Simctl

macOS license
swift-version-compatibility platform-compatibility


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

❔ 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

πŸ’» 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 xcode-swift-package
  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
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
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:

πŸ’ 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.


Stars: 43
Last commit: 4 days ago

Ad: Job Offers

iOS Software Engineer @ Perry Street Software
Perry Street Software is Jack’d and SCRUFF. We are two of the world’s largest gay, bi, trans and queer social dating apps on iOS and Android. Our brands reach more than 20 million members worldwide so members can connect, meet and express themselves on a platform that prioritizes privacy and security. We invest heavily into SwiftUI and using Swift Packages to modularize the codebase.

Submit a free job ad (while I'm testing this). The analytics numbers for this website are here.

Release Notes

2 weeks ago
  • Use Swift Argument Parser (#12 by @rsmcalister)
  • Drop Cocoapods support
  • Update CI

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics