Logo for tanaschita.com

Testing remote iOS push notifications in a simulator with simctl

Learn how to use the command-line tool simctl to simulate remote notifications in iOS.

25 Apr 2022 · 2 min read

When working with remote push notifications in iOS, testing is not always an easy task. We may not have any access to the server that will send the notifications and since remote notifications are not supported in the simulator, a device is needed to successfully receive a device token required to receive push notifications.

Nevertheless, we have the possibility to simulate a push notification in the simulator with the command-line tool called simctl.

Let's look at how to do that.

Creating and storing an .apn file

The first step to simulate a push notification in a simulator is creating and storing an .apn file. The file contains the JSON notification payload that the app would otherwise receive from the server.


"aps": {
"alert": "Hello world",
"sound": "default",
"categoryId": "1234"

Simulating push notification with simctl command-line tool

simctl is a command-line tool that provides commands to use and configure an iOS simulator. With Xcode installed, simctl is accessible through the xcrun command.

The easiest way to send a simulated notification is by following these steps:

  1. Run the app that supports and handles push notifications in a simulator
  2. Open the terminal
  3. Change to the directory where the test.apn file is stored
  4. Run xcrun simctl push booted com.tanaschita.ExampleApp test.apn. Replace com.tanaschita.ExampleApp with your app bundle identifier.

After the last step, the notification should pop up in the simulator.

Simulated notification in simulator.
Simulated notification in simulator.

With xcrun simctl push booted com.tanaschita.ExampleApp test.apn, we told simctl to send a test notification to the currently running (booted) simulator.

With that setup, we now can test different scenarios by changing the content in the test.apn file, for example to test the handling of actions or deep links from the notification.

For different iOS notification payload configuration possibilities, check out the official payload key reference.

Image of books
Further reading: Swift Power Pack
For further reading, check out the Swift Power Pack books by Paul Hudson. The bundle delivers six books from beginner to advanced around Swift topics.


Receive a monthly newsletter about the latest articles and tips.

Image of a reading marmot

Related tags

Written by

Articles with related topics

Latest articles and tips