Testing remote iOS push notifications in a simulator with simctl

Testing remote push notifications in iOS has traditionally been challenging. Developers often lack access to the production server responsible for sending notifications, and since remote notifications are not natively supported in the iOS simulator, a physical device is usually required to receive a valid push notification token.

However, Apple provides a command-line tool called simctl that allows developers to simulate push notifications directly in the simulator, making testing much easier.

Let's look at how to do that.

Architecture & Design Patterns for iOS

This book is a practical guide to essential architectural principles and design patterns for iOS development. It covers strategies for building maintainable apps with Swift and SwiftUI, including dependency injection, navigation, common patterns, and modularization.

LEARN MORE

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 normally receive from a server.

Here's an example test.apn file:

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

The above example includes an alert message and a sound notification.

Simulating a push notification with simctl

simctl is a command-line tool that allows control of the 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. Navigate to the directory containing the test.apn file.
4. Run the following command:

xcrun simctl push booted <bundle-identifier> test.apn

Replace <bundle-identifier> with your app's bundle identifier (e.g., com.example.MyApp).

After executing the command, you should see the push notification appear in the simulator, just as it would on a physical device.

Advanced usage

We can target specific simulators rather than just the booted one. First, list available simulators:

xcrun simctl list devices

Then, we can use the device UUID instead of "booted":

xcrun simctl push <device-uuid> <bundle-identifier> test.apn

Testing different notification scenarios

Once the setup is working, we can test various scenarios by modifying the test.apn file, for example:

• Deep linking: By adding a url key to test how the iOS app handles notification-based deep links.
• Action buttons: By adding an action key to test interactive notifications.
• Custom data: By including additional payload data to test how the iOS app processes it.

For a full list of notification payload options, check out Apple’s official payload key reference.