Contents

ctreffs/SwiftSimctl

Swift client-server tool to call xcrun simctl from your simulator. Automate push notification testing!

❔ 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
#!/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:

💁 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.

Package Metadata

Repository: ctreffs/SwiftSimctl

Stars: 73

Forks: 18

Open issues: 8

Default branch: master

Primary language: swift

License: MIT

Topics: cli, ios, macos, push-notifications, simctl, simulator, spm, swift, swift-package-manager, testing, tvos, uitests, xcode

README: README.md