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¶
loadstarts the session: it resets StoreKit to its default state, clears transactions and disables purchase dialogs. Every other action needs a loaded session for thatappId. Only oneappIdcan be loaded at a time on a simulator. Loading anotherappIdwhile one is loaded fails withstorekit environment active for bundleId <appId>; send clear for it before loading another bundleand changes nothing;clearthe namedappId, thenloadagain. Loading the already-loadedappIdagain starts it over.buy,refund,expire,listandclearreturntransactions, each withidentifier,productId,state(purchased,purchasing,failed,restored,deferredorunknown) andoriginalIdentifierfor renewals.setSimulatedErrormakes the nextbuyfail with that error, and is cleared after it. Purchases the app starts itself keep failing until the nextbuy,clearor anotherload. On an iOS 26 or newer simulatorbuyandexpirereturnunsupported_device(the system rejects the runner’s bundle), so use an iOS 18 simulator for them.clearresets 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 |