{"id":17424156,"url":"https://github.com/ctreffs/swiftsimctl","last_synced_at":"2025-04-06T10:15:11.640Z","repository":{"id":43864766,"uuid":"248204750","full_name":"ctreffs/SwiftSimctl","owner":"ctreffs","description":"Swift client-server tool to call xcrun simctl from your simulator. Automate push notification testing!","archived":false,"fork":false,"pushed_at":"2024-10-09T20:14:41.000Z","size":9998,"stargazers_count":70,"open_issues_count":8,"forks_count":14,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-24T18:17:12.329Z","etag":null,"topics":["cli","ios","macos","push-notifications","simctl","simulator","spm","swift","swift-package-manager","testing","tvos","uitests","xcode"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ctreffs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ctreffs"],"custom":["https://www.paypal.com/donate?hosted_button_id=GCG3K54SKRALQ"]}},"created_at":"2020-03-18T10:47:29.000Z","updated_at":"2024-10-20T06:20:31.000Z","dependencies_parsed_at":"2023-10-15T03:16:28.945Z","dependency_job_id":"e914c696-d3b7-43b1-91c9-588ebe3175fc","html_url":"https://github.com/ctreffs/SwiftSimctl","commit_stats":{"total_commits":107,"total_committers":9,"mean_commits":11.88888888888889,"dds":"0.11214953271028039","last_synced_commit":"15b11e9809e5eeb6999605a5afef626eeeba434e"},"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctreffs%2FSwiftSimctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctreffs%2FSwiftSimctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctreffs%2FSwiftSimctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ctreffs%2FSwiftSimctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ctreffs","download_url":"https://codeload.github.com/ctreffs/SwiftSimctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247464226,"owners_count":20942970,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","ios","macos","push-notifications","simctl","simulator","spm","swift","swift-package-manager","testing","tvos","uitests","xcode"],"created_at":"2024-10-17T05:06:24.736Z","updated_at":"2025-04-06T10:15:11.601Z","avatar_url":"https://github.com/ctreffs.png","language":"Swift","funding_links":["https://github.com/sponsors/ctreffs","https://www.paypal.com/donate?hosted_button_id=GCG3K54SKRALQ"],"categories":[],"sub_categories":[],"readme":"# Swift Simctl\n\n[![macOS](https://github.com/ctreffs/SwiftSimctl/actions/workflows/ci-macos.yml/badge.svg)](https://github.com/ctreffs/SwiftSimctl/actions/workflows/ci-macos.yml)\n[![license](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://github.com/ctreffs/SwiftSimctl/blob/master/LICENSE)   \n[![swift-version-compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fctreffs%2FSwiftSimctl%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/ctreffs/SwiftSimctl)\n[![platform-compatibility](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fctreffs%2FSwiftSimctl%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/ctreffs/SwiftSimctl)\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"docs/SimctlExample.gif\" target=\"_blank\"\u003e\u003cimg src=\"docs/SimctlExample.gif\" height=\"400\" alt=\"simctl-example-gif\"/\u003e\u003c/a\u003e\n\u003c/p\u003e   \n\n\nThis is a small tool (SimctlCLI) and library (Simctl), written in Swift, to automate [`xcrun simctl`](https://developer.apple.com/library/archive/documentation/IDEs/Conceptual/iOS_Simulator_Guide/InteractingwiththeiOSSimulator/InteractingwiththeiOSSimulator.html#//apple_ref/doc/uid/TP40012848-CH3-SW4) commands for Simulator in unit and UI tests.\n\nIt enables, among other things, reliable **fully automated** testing of Push Notifications with dynamic content, driven by a UI Test you control.\n\n### 🚧 Architecture\n\n\u003cp align=\"center\"\u003e\n\t\u003ca href=\"docs/Overview.png\" target=\"_blank\"\u003e\u003cimg src=\"docs/Overview.png\" height=\"500\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nSwift Simctl is made of two parts. `SimctlCLI` and `Simctl`.\n\n`Simctl` is a Swift library that can be added to your project's test bundles. \nIt provides an interface to commands that are otherwise only available via `xcrun simctl` from within your test code.\nTo enable calling these commands `Simctl` communicates over a local network connection to `SimctlCLI`.\n\n`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.\n\n### ⌨ Available Commands\n\nThe following commands will be available in code in your (test) targets:\n\n- Send push notifications with custom payload\n- Grant or revoke privacy permissions (i.e. camera, photos ...)\n- Set the device UI appearance to light or dark mode\n- Set status bar overrides (i.e. data network, time ...)\n- Uninstall app by bundle id\n- Terminate app by bundle id\n- Rename device\n- Trigger iCloud Sync\n- Open URLs including registered URL schemes\n- Erase the contents and settings of the simulator\n- Get app container\n\n## ❔ Why would you (not) use this\n\n#### ➕ Pro\n\n- Closed system (Mac with Xcode + Simulator)\n- No external dependencies on systems like [APNS](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html)\n- No custom test code bloating your code base (AppDelegate) unnecessarily\n- Push notifications can be simulated properly and the normal app cycle is preserved\n- Runs on CI machines\n- Your app stays a black box and does not need to be modified\n\n#### ➖ Contra\n\n- Needs a little configuration in your Xcode project\n- Only available for Xcode 11.4+\n\nFor specific usage please refer to the example projects **[Swift Simctl Package Example](https://github.com/ctreffs/SwiftSimctlExample)**\n\n## 🚀 Getting Started\n\nThese instructions will get your copy of the project up and running on your machine.\n\n### 📋 Prerequisites\n\n- [Xcode 11.4](https://developer.apple.com/documentation/xcode_release_notes/) and higher.\n- [Swift Package Manager (SPM)](https://github.com/apple/swift-package-manager)\n\n### 💻 Usage\n\n### 📦 Swift Package\n\nTo use Swift Simctl in your Xcode project add the package:\n\n1. Xcode \u003e File \u003e Swift Packages \u003e Add Package Dependency...\n2. Choose Package Repository \u003e Search: `SwiftSimctl` or find `https://github.com/ctreffs/SwiftSimctl.git`\n3. Select  `SwiftSimctl` package \u003e `Next` ![xcode-swift-package](docs/XcodeSwiftPackage.png)\n4. Do not forget to add the dependency to your (test) target\n5. Use `import Simctl` to access the library in your (test) target.\n\n#### Running the server alongside your tests\n\nMake sure that for the duration of your test run `SimctlCLI` runs on your host machine.\nTo automate that with Xcode itself use the following snippets as pre and post action of your test target.\n\n###### `Your Scheme` \u003e Test \u003e Pre-Actions \u003e Run Script\n\n```sh\n#!/bin/bash\nkillall SimctlCLI # cleaning up hanging servers\nset -e # fail fast\n# start the server non-blocking from the checked out package\n${BUILD_ROOT}/../../SourcePackages/checkouts/SwiftSimctl/bin/SimctlCLI start-server \u003e /dev/null 2\u003e\u00261 \u0026\n```\n\n###### `Your Scheme` \u003e Test \u003e Post-Actions \u003e Run Script\n\n```sh\n#!/bin/bash\nset -e\nkillall SimctlCLI\n\n```\n\n###### 📝 Code Example Swift Package\n\nPlease refer to the example project for an in depth code example **\u003chttps://github.com/ctreffs/SwiftSimctlExample\u003e**\n\n##### 💭 Port and settings\n\nThe default port used by the server is `8080`.  \nIf you need to use another port you need to provide it via the `--port` flag when calling `SimctlCLI` and adjust \nthe client port accordingly when setting up your test in code.  \nUse `SimctlCLI --help` to get help regarding this and other server configuration settings.\n\n\n## 🙏 Kudos\n\nSwift Simctl would not be possible without these awesome libraries:\n\n- [ShellOut](https://github.com/JohnSundell/ShellOut) - easy command line invocations\n- [Swifter](https://github.com/httpswift/swifter) - a tiny http server\n\n## 💁 How to contribute\n\nIf you want to contribute please see the [CONTRIBUTION GUIDE](CONTRIBUTING.md) first. \n\nBefore commiting code please ensure to run:\n\n- `make precommit`\n\nThis project is currently maintained by [@ctreffs](https://github.com/ctreffs).   \nSee also the list of [contributors](https://github.com/ctreffs/SwiftSimctl/contributors) who participated in this project.\n\n## 🔏 Licenses\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/ctreffs/SwiftSimctl/blob/master/LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctreffs%2Fswiftsimctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctreffs%2Fswiftsimctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctreffs%2Fswiftsimctl/lists"}