Testing on iOS

Test your PurchaseKit integration locally without receiving real Apple webhooks.

StoreKit Configuration files

Xcode's StoreKit Configuration files let you test purchases in the simulator without connecting to App Store Connect. PurchaseKit automatically detects these purchases and completes them locally.

Create a StoreKit Configuration file

  1. In Xcode, go to File → New → File
  2. Search for "StoreKit" and select StoreKit Configuration File
  3. Name it (e.g., StoreKit.storekit) and save it in your project

Creating a new StoreKit Configuration file
Creating a new StoreKit Configuration file

Sync products from App Store Connect

  1. Open your .storekit file
  2. Check Sync this file with an app in App Store Connect
  3. Select your app from the dropdown

This automatically imports your subscriptions and keeps them in sync.

Enable the configuration

  1. In Xcode, go to Product → Scheme → Edit Scheme
  2. Select Run in the sidebar
  3. Go to the Options tab
  4. Set StoreKit Configuration to your .storekit file

Enabling the StoreKit Configuration in your scheme
Enabling the StoreKit Configuration in your scheme

Clear test purchases

To reset and test again:

  1. In Xcode, go to Debug → StoreKit → Manage Transactions
  2. Select and delete previous transactions
  3. Or use Debug → StoreKit → Clear Purchase History

Testing webhooks locally

To test real Apple sandbox webhooks locally:

  1. Expose your local Rails app with Cloudflare Tunnel:
    bash
    cloudflared tunnel --url http://localhost:3000

  2. In the PurchaseKit dashboard, set your app's Sandbox Webhook URL to your tunnel URL:

    https://example-tunnel.trycloudflare.com/purchasekit/webhooks

  3. Make a sandbox purchase on a real device (not simulator)

  4. Watch the webhook arrive in your Rails logs

Sandbox subscription durations

Apple accelerates sandbox subscriptions for faster testing:

Production duration Sandbox duration
1 week 3 minutes
1 month 5 minutes
2 months 10 minutes
3 months 15 minutes
6 months 30 minutes
1 year 1 hour

Test webhook script

The example Rails app includes a script to test webhook handling:

bin/test_webhook created    # Test subscription.created
bin/test_webhook updated    # Test subscription.updated
bin/test_webhook canceled   # Test subscription.canceled
bin/test_webhook expired    # Test subscription.expired