Skip to content

In-app purchase testing

Tool What it does Platforms Needs
🛒 storeKitTest Test in-app purchases with StoreKit Testing on an iOS simulator 🤖 🍎 —

storeKitTest drives StoreKit Testing on an iOS simulator: load a .storekit configuration, then buy, refund, expire and list transactions without the App Store sandbox. It is off by default; enable it with setToolEnabled.

Parameters

Parameter Action Meaning
action all load, buy, refund, expire, setTimeRate, setSimulatedError, disableDialogs, list or clear
appId all Bundle id that keys the session
configPath load Absolute path of a .storekit file on the Mac running the simulator
productId buy Product id from the configuration
transactionId refund A transaction identifier from list
subscriptionId expire Subscription product id
timeRate setTimeRate A StoreKit renewal rate, such as realTime or oneRenewalEveryTenSeconds
simulatedError setSimulatedError unknown, paymentCancelled or storeProductNotAvailable
enabled disableDialogs true suppresses purchase dialogs

A missing argument for the action, or a configPath that is not an absolute .storekit path, fails the call before anything reaches the device.

Session

  1. load starts the session: it resets StoreKit to its default state, clears transactions and disables purchase dialogs. Every other action needs a loaded session for that appId. Only one appId can be loaded at a time on a simulator. Loading another appId while one is loaded fails with storekit environment active for bundleId <appId>; send clear for it before loading another bundle and changes nothing; clear the named appId, then load again. Loading the already-loaded appId again starts it over.
  2. buy, refund, expire, list and clear return transactions, each with identifier, productId, state (purchased, purchasing, failed, restored, deferred or unknown) and originalIdentifier for renewals.
  3. setSimulatedError makes the next buy fail with that error, and is cleared after it. Purchases the app starts itself keep failing until the next buy, clear or another load. On an iOS 26 or newer simulator buy and expire return unsupported_device (the system rejects the runner’s bundle), so use an iOS 18 simulator for them.
  4. clear resets the session, returns the final transactions and ends the session.

The session lasts as long as the runner, until clear or until your device session is released. Release clears the loaded StoreKit session and any appId you used earlier. The next session on the same simulator then starts with no purchases and no simulated error. When release cannot confirm that, it erases the simulator instead. StoreKit Testing applies the session to the runner’s own target app, so your app sees the purchases only when it runs as that target.

On a device another session holds, list without a session reads only an already-open runner connection. If none is open, it fails and leaves the device as it is.

Two calls for the same appId cannot overlap: the second fails until the first finishes. Retry it.

Results

The result has success, action, appId, transactions when the action returns them, and error when it failed.

retryable: false means the runner received the action but did not answer in time, so it may still apply. A timed-out buy can still complete. Call list before you retry it.

unsupported is set, with nothing changed on the device, when StoreKit Testing cannot run:

unsupported When What to do
unsupported_platform Android, Apple TV, Apple Watch or Apple Vision Pro Use an iOS simulator
unsupported_device A physical iPhone, or buy and expire on an iOS 26 or newer simulator Use an iOS simulator, or an iOS 18 simulator for buy and expire
unsupported_capability The connected iOS runner predates StoreKit Testing Restart the daemon to update it