How to Test Subscription Purchase on Android (Complete Guide)

Testing subscription purchases on Android is a critical quality gate because revenue flows directly through this code path. A broken purchase flow can lead to lost revenue, charge‑backs, negative revi

Introduction

Testing subscription purchases on Android is a critical quality gate because revenue flows directly through this code path. A broken purchase flow can lead to lost revenue, charge‑backs, negative reviews, and even policy violations from Google Play. Unlike a UI button that merely navigates screens, a subscription purchase touches networking, cryptographic verification, server‑side state, and the Google Play billing infrastructure. When any of those pieces misbehave, the failure may only appear under specific conditions—network latency, a rooted device, a concurrent upgrade, or a particular user persona.

This guide walks you through a complete testing strategy: why subscriptions fail in production, a detailed test matrix, manual and automated techniques, concrete code and adb examples, edge‑case scenarios that surface only after release, accessibility and security considerations, and how persona‑driven autonomous exploration (e.g., SUSA) can surface bugs that scripted tests never think to try. By the end you will have a checklist you can run before each release and a set of patterns you can embed in your CI pipeline.

---

Understanding Android Billing Library

Before writing tests you must know what the library does and where the seams are for injection or observation.

Core concepts

• BillingClient – the entry point; you start a connection, listen for updates, and launch purchase flows.
• Product IDs – strings you define in Play Console; for subscriptions they include a base plan ID and optionally an offer tag.
• Purchase token – a unique identifier Google returns after a successful purchase; you must send it to your backend for validation.
• Acknowledgment – required within three days for subscriptions; otherwise Google refunds the transaction.
• Purchase states – PURCHASED, PENDING, UNSPECIFIED_STATE. Subscriptions also have SUBSCRIPTION_STATE_ACTIVE, SUBSCRIPTION_STATE_CANCELED, SUBSCRIPTION_STATE_IN_GRACE_PERIOD, SUBSCRIPTION_STATE_ON_HOLD, SUBSCRIPTION_STATE_PAUSED.
• Proration modes – IMMEDIATE_WITH_TIME_PRORATION, IMMEDIATE_AND_CHARGE_PRORATED_PRICE, IMMEDIATE_WITHOUT_PRORATION, DEFERRED.
• Obfuscation – the library signs responses with a developer‑provided public key; you verify the signature on your server.

Typical integration snippet (Kotlin)

class BillingRepository private constructor(
    private val context: Context,
    private val billingClient: BillingClient = BillingClient.newBuilder(context)
        .setListener { billingResult, purchases ->
            // handle updated purchases
        }
        .enablePendingPurchases()
        .build()
) {
    fun start() {
        billingClient.startConnection { result ->
            if (result.responseCode == BillingResponseCode.OK) {
                // ready to query
            }
        }
    }

    fun launchPurchaseFlow(activity: Activity, skuDetails: SkuDetails) {
        val flowParams = BillingFlowParams.newBuilder()
            .setSkuDetails(skuDetails)
            .setOldPurchaseToken("") // for upgrades/downgrades fill with current token
            .build()
        billingClient.launchBillingFlow(activity, flowParams)
    }

    // …acknowledge, consume, queryPurchases, etc.
}

*The repository isolates the billing client, making it easy to swap a test double or a mock.*

---

Test Matrix

The table below organizes scenarios by category, sub‑scenario, expected outcome, and suggested verification method. Use it as a checklist when you write manual test cases or automate them.

---

Manual Testing Approach

A disciplined manual process catches issues that automated scripts might miss, especially those tied to timing, device state, or human perception.

1. Prepare the environment

• Create a license test account in Play Console → Settings → License testing. Add your tester’s Google account.
• Enable testing track (internal, closed, or open) and upload a version with BillingClient set to Environment.SANDBOX (or use the built‑in test mode).
• Clear app data before each test run:

  adb shell pm clear com.example.app

• Set device clock if you need to test trial expiration or grace periods (requires root or use Play Console’s license test to skip time).

2. Verify the happy path

1. Launch the app, navigate to the subscription screen.
2. Tap Subscribe for a plan that has a test price (e.g., $0.99/month).
3. In the Play Store sheet, select the pre‑configured test credit card (e.g., “Always succeed”).
4. Complete the purchase.
5. Observe the app UI: a confirmation toast or dialog should appear.
6. Pull the purchase token from logs (adb logcat | grep "Purchase token").
7. Call your verification endpoint with the token and assert the response contains {"state":"ACTIVE"}.
8. Verify that premium features are unlocked in the UI.

3. Test error paths

• Network loss – enable airplane mode toggle mid‑flow:

  adb shell svc wifi disable   # disable
  # after user taps buy, wait a few seconds then
  adb shell svc wifi enable   # re‑enable

Expect a graceful error dialog and no token.

• User cancellation – press the back button on the Play Store confirmation screen.
• Invalid SKU – change the product ID in code to a non‑existent string and verify ITEM_UNAVAILABLE.

4. Exercise edge cases

• Rapid double‑tap – use a script or a second finger to tap twice within 100 ms. Verify only one flow starts.
• Orientation change – while the Play Store dialog is visible, rotate the device:

  adb shell settings put user_rotation 1   # landscape
  # complete purchase
  adb shell settings put user_rotation 0   # portrait

• Background/interrupt – press Home, open another app, then return to your app after purchase completes.
• Upgrade/downgrade – purchase a basic plan, then immediately initiate an upgrade to a premium plan with a defined proration mode. Verify the backend receives a SUBSCRIPTION_UPDATE event with correct proration.
• Free trial – use a license test account that grants a free trial; after the trial period (you can fast‑forward via Play Console license test), confirm the first paid charge occurs and the subscription stays active.
• Grace period & account hold – simulate a declined card (use the “Always fail” test card). After the first failed charge, check that the user still has access for the grace period length defined in Play Console. After grace expires, confirm the state moves to ON_HOLD and access is blocked.
• Pause – if your app supports pausing, go to Play Store → Subscriptions → select your subscription → Pause, choose a duration, and confirm the app reflects the paused state and that premium features are greyed out.
• Price change – increase the price of a plan in Play Console, then open the subscription screen; a dialog should appear notifying the user of the upcoming change.

5. Accessibility checks

• Turn on TalkBack (Settings > Accessibility > TalkBack). Swipe through each screen of the purchase flow. Every button, checkbox, and text field should announce a meaningful label.
• Set Font size to the largest setting and verify no clipping.
• Enable Color correction or Dark theme via developer options and run a contrast analyzer (e.g., Android Accessibility Test Framework) to ensure minimum contrast ratios.

6. Security & privacy verification

• Run the purchase flow with logcat capture:

  adb logcat -c   # clear
  # perform purchase
  adb logcat -d > purchase_log.txt

Search the file for any substring that looks like a purchase token (a long base64‑ish string). It should not appear.

• Use a proxy like Charles or Mitmproxy to inspect network traffic. Confirm that calls to your verification endpoint are over TLS and that the developer payload (if you use one) is not exposed in clear text.
• Check the app’s internal storage for leftover purchase data:

  adb shell run-as com.example.app ls /data/data/com.example.app/files
  adb shell run-as com.example.app cat /data/data/com.example.app/shared_prefs/*.xml

No plain token should be present.

7. Performance sanity

• Use Android Studio Profiler to record CPU and memory while repeating the purchase flow 10 times. Look for spikes or steady growth.
• Measure end‑to‑end latency with adb shell am start-activity -W -n com.example.app/.PurchaseActivity. The “TotalTime” field should be under 2000 ms on a mid‑tier device (e.g., Pixel 4a).

8. Cleanup

After each test cycle, clear data or call your backend to acknowledge and revoke the purchase (if you have a test revocation endpoint) to keep the sandbox clean.

---

Automated Testing Approaches

Automation gives you repeatability and lets you run the matrix on every commit. Below are layers you can combine.

Unit layer – mocking BillingClient

Because BillingClient is final, wrap it in an interface (as shown in the repository snippet). Then you can inject a mock.

interface IBillingService {
    fun startConnection()
    fun launchPurchase(activity: Activity, skuDetails: SkuDetails)
    fun acknowledgePurchase(purchaseToken: String)
    fun queryPurchases(): List<Purchase>
}

class BillingServiceImpl @Inject constructor(
    @ApplicationContext private val ctx: Context
) : IBillingService {
    private val client = BillingClient.newBuilder(ctx)
        .setListener { result, purchases -> /* … */ }
        .build()
    // delegate methods …
}

// In ViewModel
class PurchaseViewModel @Inject constructor(
    private val billing: IBillingService
) { /* … */ }

// Test
@Test
fun `purchase success triggers acknowledgment`() {
    val billingMock = mock(IBillingService)
    val viewModel = PurchaseViewModel(billingMock)
    // simulate user click
    viewModel.onSubscribeClicked()
    verify(billingMock).launchPurchase(any(), any())
    // simulate Play Store returning a purchase
    val fakePurchase = Purchase.newBuilder()
        .setPurchaseToken("tok_123")
        .setSku("sub_monthly")
        .setPurchaseState(Purchase.PurchaseState.PURCHASED)
        .build()
    viewModel.onPurchaseUpdated(listOf(fakePurchase))
    verify(billingMock).acknowledgePurchase("tok_123")
}

*Use Mockito or MockK; run with JUnit4/JUnit5 on the JVM (Robolectric optional if you need Android resources).*

Instrumentation layer – Espresso/UIAutomator

You cannot directly interact with the Play Store purchase dialog, but you can verify that your app launches the correct intent and handles the result.

@RunWith(AndroidJUnit4::class)
class PurchaseFlowTest {

    @Test
    fun launchPurchaseFlow_showsConfirmation() {
        // navigate to subscription screen
        onView(withId(R.id.btn_subscribe)).perform(click())

        // verify that the app started the billing flow via a callback
        // We cannot assert Play Store UI, but we can check that a PurchaseUpdatedListener
        // receives a purchase after we mock the BillingClient in the test rule.
        // For end‑to‑end we rely on Firebase Test Lab with a real Play Store account.
    }
}

To test the actual Play Store UI you need a real or managed Google Play environment, which is why services like Firebase Test Lab or Google Play’s internal testing track are used.

Firebase Test Lab + internal test track

1. Upload your APK/AAB to the internal test track.
2. Create a test matrix in Firebase Test Lab that selects a range of devices (different API levels, screen sizes, manufacturers).
3. In the test script (using Espresso or UiAutomator), after launching the purchase flow, use the test credit card provided by Play Console’s license testing to complete the purchase.
4. After the test finishes, pull the logcat and verify that the purchase token appears and that your backend received a valid verification request.

Sample gcloud command to kick off a test:

gcloud firebase test android run \
    --type instrumentation \
    --app app-debug.apk \
    --test tests-apk.apk \
    --device model=Pixel3,version=28,locale=en,orientation=portrait  \
    --directories-to-pull /sdcard/logcat

End‑to‑end with Appium (optional)

If you need to test a hybrid flow that includes a web view for managing subscriptions (e.g., a web portal), Appium can drive both the native Android app and the web context.

AppiumDriver<MobileElement> driver = new AndroidDriver<>(new URL("http://localhost:4723/wd/hub"), caps);
// navigate to subscription screen
driver.findElement(By.id("btn_subscribe")).click();
// switch to WebView if needed
Set<String> contexts = driver.getContextHandles();
for (String ctx : contexts) {
    if (ctx.contains("WEBVIEW")) {
        driver.context(ctx);
        break;
    }
}
fillInWebForm("//input[@name='cardNumber']", "4000000000000002"); // test card
driver.findElement(By.id("confirm_purchase")).click();
driver.context("NATIVE_APP");
assertTrue(driver.findElement(By.id("purchase_success")).isDisplayed());

Autonomous, persona‑driven exploration (SUSA)

SUSA can be dropped into your CI as an additional step that complements scripted tests. It works by:

• Installing the APK on a device or emulator.
• Launching the app and then letting a set of persona agents explore the UI for a configurable time (e.g., 5 minutes per persona).
• Each agent follows a behavior profile:
• *Curious* – taps every visible element, long‑presses, scrolls randomly.
• *Impatient* – performs rapid actions, spams back button, tries to skip screens.
• *Novice* – follows suggested UI hints, takes longer pauses.
• *Adversarial* – injects overlay windows, attempts to click outside bounds, uses accessibility services to hijack focus.
• *Accessibility* – enables TalkBack, changes font size, uses switch access.
• *Power user* – toggles developer options, uses USB keyboard shortcuts, rotates device aggressively.

During exploration SUSA automatically:

• Detects crashes, ANRs, and unhandled exceptions via logcat monitoring.
• Records every UI transition and flags dead ends (screens where no further action is possible).
• Checks for purchase‑related anomalies: multiple purchase flows launched simultaneously, purchase token appearing in logs, UI elements that remain enabled after a purchase, or purchase dialogs that never dismiss.
• Generates a regression script (Appium + Playwright) for any flow it discovered, so you can add those scenarios to your automated suite.

Example of a bug that SUSA found in a real subscription flow (anonymized):

*An *Impatient* agent double‑tapped the subscribe button while the Play Store dialog was still animating. The app launched a second billing flow, resulting in two purchase tokens being generated. The backend only acknowledged the first token, leaving the second in a PENDING state that never resolved, causing the user to be charged twice on renewal.*

Because traditional scripts usually perform a single, linear tap, they never reproduced the race condition. SUSA’s random interleaving uncovered it.

To run SUSA locally:

pip install susatest-agent
susatest run --apk path/to/app.apk \
    --personas curious impatient novice adversarial accessibility poweruser \
    --duration 300   # seconds per persona

The tool outputs a JSON report with PASS/FAIL per flow, plus any discovered regression scripts.

---

Code Examples – Practical Snippets

1. BillingClient lifecycle helper (Kotlin)

object BillingManager {
    private var client: BillingClient? = null

    fun init(context: Context) {
        client = BillingClient.newBuilder(context)
            .setListener { billingResult, purchases ->
                when {
                    billingResult.responseCode == BillingResponseCode.OK -> {
                        purchases?.let { handlePurchases(it) }
                    }
                    billingResult.responseCode == BillingResponseCode.USER_CANCELED -> {
                        // handle cancel
                    }
                    else -> {
                        // handle error
                    }
                }
            }
            .enablePendingPurchases()
            .build()
    }

    fun start() {
        client?.startConnection { result ->
            if (result.responseCode == BillingResponseCode.OK) {
                // ready
            }
        }
    }

    private fun handlePurchases(purchases: List<Purchase>) {
        purchases.forEach { purchase ->
            if (purchase.purchaseState == Purchase.PurchaseState.PURCHASED) {
                // verify on backend, then acknowledge
                acknowledgeIfNeeded(purchase.purchaseToken)
            }
        }
    }

    private fun acknowledgeIfNeeded(token: String) {
        // call your verification endpoint, then:
        client?.acknowledgePurchase(
            AcknowledgePurchaseParams.newBuilder()
                .setPurchaseToken(token)
                .build()
        ) { /* handle result */ }
    }

    // expose query, launchFlow, etc.
}

*This singleton isolates all billing logic, making it trivial to replace client with a fake in tests.*

2. Fake BillingClient for unit tests (using Mockito)

class FakeBillingClient(
    private val purchases: List<Purchase> = emptyList()
) : BillingClient(ApplicationProvider.getApplicationContext()) {
    override fun startConnection(listener: BillingClientStateListener) {
        // simulate instant success
        listener.onBillingServiceConnected()
    }

    override fun launchBillingFlow(activity: Activity, flowParams: BillingFlowParams) {
        // do nothing – the test will manually invoke the listener
    }

    override fun acknowledgePurchase(
        acknowledgePurchaseParams: AcknowledgePurchaseParams,
        listener: BillingResponseListener
    ) {
        // simulate success
        listener.onBillingResponse(BillingResponse.BillingResponseOK)
    }

    override fun queryPurchasesAsync(
        queryPurchasesParams: QueryPurchasesParams,
        listener: PurchasesUpdatedListener
    ) {
        listener.onPurchasesUpdated(
            BillingResponse.BillingResponseOK,
            purchases
        )
    }
}

*Inject FakeBillingClient into your repository; you can pre‑load it with a purchase that has a known token to test acknowledgment logic.*

3. ADB command to simulate a network drop and restore

# Disable Wi‑Fi
adb shell svc wifi disable
# (user taps buy, wait a few seconds)
# Re‑enable Wi‑Fi
adb shell svc wifi enable

*You can wrap this in a shell script that loops through a purchase flow to verify graceful handling.*

4. Fast‑forwarding trial with Play Console license test

In Play Console → License testing → Add a license test account → set License Response to GRANTED and Validity Timestamp to a future date (e.g., +30 days). The app will treat the user as having an active subscription instantly, letting you test post‑trial UI without waiting.

5. Verifying purchase token absence in logcat (bash)

adb logcat -c
# run your purchase flow
adb logcat -d -s PurchaseManager | grep -i "token" || echo "No token leaked"

*If the grep returns nothing, the token is not present in the filtered log.*

---

Edge Cases That Only Show in Production

---

Accessibility & Localization Checklist