Terminal
Terminal/Skill
Covers testing Google Play Billing with license testers, test responses, sandbox purchases, and accelerated renewals and grace periods.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill testingA billing build that runs on your laptop is not evidence that it works in production. Real users hit payment declines, pending cash payments, grace periods, and account holds. Use Google's license testers, Play Billing Lab, and the accelerated sandbox to exercise every state you claim to support before you release.
Before you test anything, confirm the environment is wired up. Skipping a step here leads to purchase dialogs that charge real money or flows that never show test cards.
Run through this checklist:
enablePendingPurchases flag: Verify your BillingClient opts in to pending transactions if you sell in markets with cash payments. Without this, slow test cards will not behave correctly.If any item is missing, fix that first. License tester tooling is invisible otherwise.
Pick a strategy that matches what you changed. Running all 11 subscription test cases on every PR is wasteful. Running none is reckless.
| Change type | Minimum coverage |
|---|---|
| New purchase flow or product catalog | New purchase, acknowledgment, entitlement grant |
| Subscription lifecycle logic | Renewal, grace period, account hold, cancellation |
| Plan change or upgrade code | Each replacement mode you support, plus linkedPurchaseToken handling |
| RTDN or server integration | Renewal, grace, hold, revoke, refund notifications end to end |
| Error handling or retry paths | Response simulator sweep: SERVICE_DISCONNECTED, NETWORK_ERROR, ITEM_ALREADY_OWNED, USER_CANCELED, BILLING_UNAVAILABLE |
| Pre release candidate | Full 11 case suite plus one real payment on the cheapest SKU |
Inside the Play purchase dialog, license testers see four virtual instruments instead of real cards. Each one forces a deterministic outcome, so pick the one that matches the path you want to exercise.
| Test instrument | Result | Use when you are testing |
|---|---|---|
| Test card, always approves | Immediate success, BillingResponseCode.OK | Happy path, acknowledgment, entitlement grant |
| Test card, always declines | Immediate failure, BillingResponseCode.ERROR | Decline UI, error messaging, absence of entitlement grant |
| Slow test card, always approves | Pending state, then success after minutes | Pending purchase handling, UI state, PurchasesUpdatedListener firing twice |
| Slow test card, always declines | Pending state, then final failure | Pending decline path, cleanup of pending UI |
Before you pick an instrument, decide what signal proves the test passed: a specific response code, a purchase state transition, an RTDN on your server, or an entitlement change in the app. Write it down first.
If you are exercising the subscription state machine, choose one of these as your first target:
linkedPurchaseToken handling on both app and server.Open your app on the test device signed in with the license tester account.
PurchasesUpdatedListener fires with BillingResponseCode.OK and a Purchase in the PURCHASED state.queryPurchasesAsync and confirm the purchase is returned as active.To prove your acknowledgment path works, repeat the flow but skip step 5 on purpose:
If the entitlement is still present after 3 minutes, your app is caching state without rechecking. Fix that before shipping.
Test subscriptions run on a compressed schedule automatically. You do not configure this.
| Production renewal period | Test renewal period |
|---|---|
| Weekly | 5 minutes |
| Monthly | 5 minutes |
| Quarterly | 10 minutes |
| Semi annual | 15 minutes |
| Yearly | 30 minutes |
Intermediate states compress too: free trial runs 3 minutes, grace period runs 5 minutes, account hold runs 10 minutes. Test subscriptions cancel after 6 renewals regardless of period, so plan accordingly.
To watch a full lifecycle in under 20 minutes:
SUBSCRIPTION_RENEWED and the entitlement remains active.SUBSCRIPTION_IN_GRACE_PERIOD, SUBSCRIPTION_ON_HOLD, and SUBSCRIPTION_CANCELED each landed.Use Play Billing Lab to force specific transitions instead of waiting on timers when you only need to verify one state. It also lets you reset trial eligibility so you can rerun trial sign up on the same account.
Play Billing Lab ships a response simulator that forces any Play Billing Library method to return a chosen BillingResult. Configure a rule, run the flow, confirm your app recovers.
Minimum response codes to cover:
SERVICE_DISCONNECTED during purchase: your app reconnects and retries.NETWORK_ERROR on acknowledgePurchase: your app retries, because unacknowledged purchases refund in 3 days in production.ITEM_ALREADY_OWNED on launchBillingFlow: your app refreshes purchases and messages the user correctly.USER_CANCELED: your app returns to the previous screen without an error banner.BILLING_UNAVAILABLE on connect: your app hides purchase options gracefully.If you accept cash payments, configure your client once and then test with the slow approve card.
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases(
PendingPurchasesParams.newBuilder()
.enableOneTimeProducts()
.enablePrepaidPlans()
.build()
)
.build()
Guard entitlement grants by purchase state:
when (purchase.purchaseState) {
Purchase.PurchaseState.PURCHASED -> grantAndAcknowledge(purchase)
Purchase.PurchaseState.PENDING -> showPendingUi(purchase)
else -> Unit
}
Verify both the pending to purchased transition and the pending to cancelled transition deliver a second PurchasesUpdatedListener callback, and that your server processes the matching RTDN.
License tester cards do not exercise 3D Secure prompts, card verification, refund processing, or financial reporting. Before your first production push:
queryPurchasesAsync. The 3 minute auto refund window exposes this.PENDING state. The slow decline card exposes this.CHARGE_PRORATED_PRICE on a downgrade. It will fail at runtime.