Developer Console

Design and Run Test Cases for IAP

Amazon provides the App Tester tool to unit test your app before you submit it to the Appstore. To effectively test your app, create a set of test cases that will give you comprehensive coverage for the various scenarios that users will encounter when interacting with your app.

Your app's interaction with the Amazon Appstore is isolated to the API libraries, so your app will not know that it is talking with App Tester. Because you have control over the responses given by the App Tester, you can test your app's behavior under any response condition.

This page describes a set of test cases that should cover most user scenarios for your app's implementation of IAP and discusses how to run those test cases using App Tester. For information more information about App Tester, see the following pages:

Summary of Test Cases

When you are testing the IAP implementation in your app, plan your test cases to cover as many code paths as possible. The following list of transaction types should give you good coverage for the various scenarios that you might expect to encounter with your app's users:

  • Get User Data (Successful/Failed)
  • Get Product Data (Successful/Failed)
  • Purchase Request (Successful/Failed/Already purchased/Invalid SKU)
  • Purchase Updates Request (Successful/Failed)
  • NotifyFulfillment (Successful/Unavailable)
  • Subscription Check (Valid/Expired)
  • Verify Receipts (RVS)

Get User Data

Both the Amazon Appstore and App Tester tool track transactions by User ID. Because your app should be able to handle multiple users at a time, any user-specific function in the app should check the current logged-in User ID at the appropriate points, such as the Android lifecycle method onResume(). When retrieving user data, you can receive either a SUCCESSFUL or FAILED response.

To test Get User Data for either response:

  1. In App Tester, go to the User Account Settings tab, and make sure that the User ID is set.
  2. Set the GetUserData API Preference:
    • To test for a SUCCESSFUL response, set the preference to DEFAULT or SUCCESSFUL.
    • To test for a FAILED response, set the preference to FAILED.
  3. Call getUserData.
  4. Process the response using onGetUserDataResponse.

Get Product Data

When performing a test for Get Product Data, the App Tester will return product data from the JSON file in DEFAULT mode. When retrieving product data, you can receive either a SUCCESSFUL or FAILED response.

To test Get Product Data:

  1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
  2. Set the GetProductData API Preference:
    • To test for a SUCCESSFUL response, set the preference to DEFAULT or SUCCESSFUL.
    • To test for a FAILED response, set the preference to FAILED.
  3. Call getProductData.
  4. Process the response using onGetProductDataResponse.

Purchase

To simplify implementation and testing, the Purchase API works identically for all three types of IAP items:

  • Subscriptions: One-time purchase by a user
  • Entitlements: One-time purchase by a user
  • Consumables: Can be purchased multiple times by the same user

To test the Purchase API:

  1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
  2. Set the Purchase API Preference. Make sure to test each of the four available conditions:
    • To test for a SUCCESSFUL response, set the preference to DEFAULT or SUCCESSFUL.
    • To test for a FAILED response, set the preference to FAILED.
    • To test for an ALREADY_PURCHASED request, set the preference to ALREADY_PURCHASED.
    • To test for an INVALID_SKU, set the preference to INVALID_SKU.
  3. Call purchase.
  4. Process the response using onPurchaseResponse.
    Successfully purchased content will appear on the App Tester's Manage Transactions tab.

Alternately, you can test the "already purchased" condition by progressing through a typical purchase workflow:

  1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
  2. Set the Purchase API Preference to DEFAULT.
  3. Make a successful purchase for a subscription or entitlement SKU. (Consumables may be purchased multiple times.)
  4. Call purchase again using the same SKU.
  5. Process the response using onPurchaseResponse.
    Successfully purchased content will appear on the App Tester's Manage Transactions tab.

Purchase Updates Request

To ensure that a user has access to their correct content, call the Purchase Update Requests API when your app starts interacting with that user (in the onResume() method of the Android lifecycle), Successful responses can include zero or many receipts from previous transactions, depending on the contents of the Manage Transactions tab in the App Tester.

You can verify tokens present in the receipts using the Receipt Verification Service (RVS).

To test Purchase Update Requests:

  1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
  2. Successfully purchase the SKUs that you configured.

  3. Set the GetPurcaseUpdates API Preference:
    • To test for a SUCCESSFUL response, set the preference to DEFAULT or SUCCESSFUL.
    • To test for a FAILED response, set the preference to FAILED.
  4. Call getPurchaseUpdates.
  5. Process the response using onPurchaseUpdatesResponse.

If you want to generate a SUCCESSFUL but empty response, use the following workflow:

  1. Verify that your JSON file for App Tester contains the SKUs and product definitions that you want to test.
  2. Successfully purchase the SKUs that you configured.
  3. Set the getPurchaseUpdates API Preference to DEFAULT.
  4. On the Manage Transactions tab, delete all transactions.
  5. Call getPurchaseUpdates.
  6. Process the response using onPurchaseUpdatesResponse.

Notify Fulfillment

Call the Notify Fulfillment API to verify fulfillment and test for the available receipt states in IAP. You can use the following workflow to test fulfillment for Consumable or Entitlement items.

To test Notify Fulfillment:

  1. Call purchase for a consumable item.
  2. Note the receipt for the purchased item.
  3. Call getPurchaseUpdate.
  4. Note the returned consumable receipt.
  5. In App Tester, on the Manage Transactions tab, verify that the consumable is set to be delivered.
  6. Call notifyFullfilment:
    • To test the "fulfilled" condition, set notifyFulfillment to SUCCESSFUL.
    • To test the "unavailable" condition, set notifyFulfillment to UNAVAILABLE.
  7. In App Tester, verify the purchase on theh Manage Transactions tab:
    • If you are testing the "fulfilled" condition, the consumable should be listed as Fulfilled.
    • If you are testing the "unavailable" condition, the consumable should be listed as Unavailable.

Subscription Check

You can use App Tester to verify both valid and expired subscriptions. If you cancel an active subscription transaction from the Manage Transactions tab, App Tester treats that transaction as an expired subscription.

To test for a valid subscription:

  1. Make a successful purchase of a subscription SKU.
  2. Go to the Manage Transactions tab, and verify that the transaction is listed there.
  3. Call getPurchaseUpdates.
  4. Process the response using onPurchaseUpdatesResponse.
  5. From the returned receipts, verify that the most recent receipt (by start date) for the SKU that you purchased.
  6. Verify that the value of the end date is null.

To test for an expired subscription:

  1. Make a successful purchase of a subscription SKU.
  2. Go to the Manage Transactions tab, and verify that the transaction is listed there.
  3. On the Manage Transactions tab, cancel the transaction.

  4. Call getPurchaseUpdates.
  5. Process the response using onPurchaseUpdatesResponse.
  6. From the returned receipts, verify that the most recent receipt (by start date) for the SKU that you purchased.
  7. Verify that the value of the end date is not null.

Verify Receipts

Amazon provides a Receipt Verification Service (RVS), which you can use to validate purchases from your back-end server. See the RVS documentation to learn more about this service.

IAP Response Matrix

The following matrix maps IAP API responses to their App Tester properties and other testing conditions:

IAP API Response Async Invocation AppTester Property Set JSON Used? Notes
PurchaseRequestStatus. SUCCESSFUL purchase Purchase API, DEFAULT or SUCCESSFUL Yes As long as the purchase is for a valid SKU in the JSON file, a successful response is returned
PurchaseRequestStatus. FAILED purchase Purchase API, FAILED Yes (to display item information) The App Tester Forces a Failed response when this property is set to FAILED in Preference Page or if the Purchase Confirmation Dialog is closed
PurchaseRequestStatus. INVALID_SKU purchase Purchase API, INVALID_SKU No The App Tester Forces any Purchase Request to return INVALID_SKU when this property is set in Preference Page
PurchaseRequestStatus. ALREADY_PURCHASED purchase Purchase API, ALREADY_PURCHASED Yes The App Tester Forces any Purchase Request to return ALREADY_PURCHASED when this property is set to ALREADY_PURCHASED in the API Response Settings tab or SKU has been purchased before
GetProductDataStatus. SUCCESSFUL getProductData Get Product Data API, DEFAULT or SUCCESSFUL Yes As long as the request is for a valid SKU in the JSON file, a successful response is returned
GetProductDataStatus. FAILED getProductData Get Product Data API, FAILED No App Tester Forces any Product Data Request to return FAILED when this property is set
GetUserDataStatus. SUCCESS getUserData Get User Data API, DEFAULT or SUCCESSFUL No The App Tester will always return the User Id stored in the App Tester when this property is set in the API Response Settings tab
GetUserIdRequestStatus. FAILED getUserData Get User Data API, FAILED No The App Tester forces a failed response when this property is set in the API Response Settings tab
PurchaseUpdatesResponseStatus. SUCCESS getPurchaseUpdates Purchase Updates API, SUCCESSFUL No The App Tester will always return what is in the Transaction log when this property is set in the API Response Settings tab
PurchaseUpdatesResponseStatus. FAILED getPurchaseUpdates Purchase Updates API, FAILED No The App Tester will force a failed response when this property is set in the API Response Settings tab

Last updated: Mar 31, 2022