Notification Delivery Testing

Use this reference for Simulator, provider, device, and delivery diagnostics. Test the boundary that changed instead of treating a banner as proof that every layer is correct.

Choose the test boundary

Current Xcode/OS hosts may let iOS Simulator register with the APNs Sandbox. Treat support as host/runtime-dependent, not as a universal Simulator promise. Keep a physical-device check for production, signing, and hardware-specific behavior. Simulator APNs tokens are not interchangeable with device tokens.

Provider-free Simulator smoke test

Create a payload with the app's bundle identifier:

{
  "Simulator Target Bundle": "com.example.myapp",
  "aps": {
    "alert": { "title": "Test", "body": "Provider-free smoke test" },
    "sound": "default"
  },
  "route": "inbox"
}

Then run:

xcrun simctl push booted com.example.myapp payload.apns

Use this path to isolate payload decoding, delegate behavior, categories, and extension presentation. It does not exercise the APNs provider path.

Provider and device matrix

For a remote test, record the environment, bundle/topic, push type, priority, expiration, token source, APNs response, app callback, and final presentation. Use apns-push-type: alert for visible notifications and apns-push-type: background with priority 5 for background notifications. Background pushes are hints: they can be delayed, coalesced, throttled, or dropped, and they must not be used as a timer.

When a Simulator registration fails, inspect the Xcode/OS runtime, host architecture, signing, network, CI/VM restrictions, and entitlements before calling it an Apple-wide limitation. Re-register after reinstalling and log the opaque token length and environment without treating a cached token as truth.

Delivery debugging checklist

• Confirm the app's topic/bundle identifier and environment match the token.
• Capture APNs provider status and reason, not only the client log.
• Verify the application-delegate registration callback and upload each token.
• Inspect aps placement, push type, priority, expiration, and collapse ID.
• Check authorization, Focus, app state, notification settings, and category IDs.
• For extensions, verify the alert plus mutable-content: 1 trigger and the exact-once completion path in service-extension.md.
• Repeat production or hardware-specific checks on a physical device.

For the original all-in-one recipes, read notification-patterns-complete.md.