StoreKit Testing in Xcode: Local Products, Simulator Purchases, and Automated Tests
iOS 14-era StoreKit testing moves much of in-app purchase work into Xcode. Instead of waiting for App Store Connect setup to propagate, you can describe products locally, run purchases in the Simulator, drive scenarios programmatically in tests, and adjust subscription timing and transaction state from Xcode or sandbox settings.
Quick decision checklist
Use this checklist to decide which local-testing path fits the scenario you need to cover:
- Define products locally first when App Store Connect is not ready or has not propagated.
- Use Simulator purchases for manual end-to-end checks without a device.
- Use StoreKitTest with XCTest when the purchase flow must run repeatedly and without user interaction.
- Use Xcode transaction controls for refunds, cancellations, cross-grades, and interrupted purchases.
- Use sandbox Manage controls on device for subscription switching and introductory-offer eligibility resets.
- Adjust subscription duration when renewal timing is the bottleneck.
StoreKit Configuration File: define products before App Store Connect
A StoreKit Configuration File is a JSON-encoded Xcode file that describes SKProducts for testing. You populate it with the details you would normally enter for in-app purchases in App Store Connect, including product IDs, subscription groups, and introductory offers.
Attach the file to a scheme by opening Edit Scheme, choosing Run, and selecting the configuration. The same file is reused by automated tests, so manual and automated runs share one product definition.
Practical benefit: check product presentation and behavior early, and exercise features such as cross-grades and interruptions before they are available in production. One caution matters for verification: receipts produced from a local configuration are signed with a different, app-specific certificate. Export that certificate from the configuration editor menu and use it when verifying receipts.
Purchases in the Simulator: manual checks without a device
With a configuration selected in the scheme, the iOS Simulator can run purchases in the Local StoreKit environment. That removes the need for a physical device for many checks and lets automated tests make purchases.
The purchase prompt closely matches production, including the product-detail UI, and the same experience applies on physical devices. If purchases do not work in the Simulator, first confirm the scheme actually points at the intended configuration file.
StoreKitTest Framework: automate success, failure, and interruptions
StoreKitTest is a framework for automated tests that gives programmatic control over the Local StoreKit environment. It uses the same configuration files and can complete purchases without user interaction.
Use it to build integration tests around outcomes that are hard to reach manually: successful purchases, failed purchases, interrupted purchases, external transactions, and subscription offers. Pair it with XCTest so unit and UI tests can cover purchase logic inside Xcode's local environment.
New Sandbox Controls on Device: manage subscriptions and offer eligibility
On device, the Sandbox Account section in iOS Settings gains a Manage option. From there you can enable or disable renewal receipts and view active subscriptions for the sandbox account. Opening an active subscription shows a screen similar to the Manage Subscription page, where you can change to a different subscription.
A sandbox-only Reset Eligibility button clears introductory-offer eligibility for the sandbox user. That distinction is useful: use Manage for subscription state and offer-eligibility resets, and use Xcode transaction controls when you need to act on a specific transaction such as a refund or cancellation.
Other Xcode Tools for Local Testing: faster renewals and transaction control
Two Xcode controls shorten the loop. Selecting the sandbox duration of subscriptions speeds up purchases by adjusting renewal timing, so long cycles can be tested sooner. The transaction interface lists transactions made by a user and lets you perform cross-grades, cancellations, and refunds, and simulate interrupted purchases, such as those caused by a payment issue.
Example workflow: define a monthly subscription and an introductory offer in the configuration file, attach it to the scheme, run in the Simulator, buy the subscription, shorten the sandbox duration, then use the transaction controls to cross-grade or cancel and confirm the app responds correctly. For repeatable coverage, move the same scenario into a StoreKitTest case.
Frequently asked questions
Do I need App Store Connect products before I can test?
No. You can define products locally in Xcode first, then check how they behave before App Store Connect setup is complete or propagated. That includes flows that previously only worked in production, such as subscription cross-grades and interruptions.
Can I test purchases in the Simulator?
Yes. Select the configuration file in the scheme under Run, and the Simulator can run purchases in the Local StoreKit environment without a physical device. The purchase prompt resembles the production prompt and shows product details.
Why does receipt verification behave differently locally?
Receipts from a local configuration use a different, app-specific certificate. Export that certificate from the StoreKit configuration editor menu and use it for verification.
How do I retest an introductory offer in sandbox?
Use the sandbox Manage section on device to view active subscriptions, switch subscriptions, toggle renewal receipts, and reset introductory-offer eligibility for the sandbox user instead of creating a new sandbox account each time.