Testing push notifications in the Simulator with Xcode 11.4

For years we've had to resort to using physical devices when testing push notifications. With Xcode 11.4, Apple finally gives developers the tools needed to test push notifications on the iOS Simulator. I'm going to assume you already know how to add push notifications to your app. If you've never added push notifications to an app before, I have a post that describes how to set up and test push notifications without a third-party service. That post should get you all set up to follow along with this post.

Sending a test push from the command line

Xcode comes with several command-line tools that allow you to run your tests, builds and other tasks directly from the Terminal in macOS. If you have Xcode installed, it should automatically install the command line tools on its first launch. If you've followed my guide on having multiple Xcode versions installed, make sure to select Xcode 11.4 or newer by running xcversion select 11.4 and replace 11.4 with the version of Xcode you want to use. Doing this will make sure the Xcode command line tools point to the correct toolchain.

When you have an iOS 13.4 or newer simulator running, all you need to send a push notification is an apns notification payload. The payload should look similar to the following:

{
  "Simulator Target Bundle": "com.donnywals.SilentPushDemo",
  "aps": {
    "alert": {
      "title": "Push on the simulator",
      "subtitle": "So cool...",
      "body": "This notification is going to show up in the simulator!"
    }
  }
}

The formatting of the push notification is the same as it would be when you send it from a server to a device. The only exception is the "Simulator Target Bundle" top-level key. This key should not be present in push notifications that you send from a production server. To send this push notification, you can run the following terminal command:

xcrun simctl push booted test_push.apns

This will send a test push notification to all booted simulators. The last argument passed to this command is the path to the file that contains the test push notification. In this case, it's a file called test_push.apns which exists in the directory as the one I'm running the command from.

The "Simulator Target Bundle" can be omitted from the file, but then the terminal command would be slightly different:

xcrun simctl push booted <your-bundle-identifier> test_push.apns

When you don't include your app's bundle identifier in the payload, you need to specify the bundle identifier of the receiving app in the command. Make sure you replace <your-bundle-identifier> with the receiving application's bundle identifier.

Sending a test push notification without the command line

If you're not comfortable using the command line to send a test push, you can also drag your test push notification directly to the simulator to have it delivered to that specific simulator immediately.

When doing this, make sure your file has .apns as its extension, and it must include the "Simulator Target Bundle" top-level key so the simulator knows which application should receive your test push.

In Summary

The ability to test push notifications in the simulator is a feature that iOS developers have wanted for a very long time, and I think that it's great that Apple has finally provided us with this ability. Especially because they managed to make the process so straightforward by keeping everything local to the machine you're developing on.

If you want to test with notifications that are actually generated and sent from your server, you still need to use a physical device because the simulator doesn't support true remote notifications just yet. However, I think this is a great step in the right direction and I'm sure I will use this feature regularly.

If you have any questions or feedback for me, make sure to reach out on Twitter.