Locally test module installs

The Play Core Library allows you to locally test your app’s ability to do the following, without connecting to the Play Store:

• Request and monitor module installs.
• Handle install errors.
• Use SplitCompat to access modules.

This page describes how to deploy your app's split APKs to your test device so that Play Core automatically uses those APKs to simulate requesting, downloading, and installing modules from the Play Store.

Although you don't need to make any changes to your app's logic, you need to meet the following requirements:

• Download and install the latest version of bundletool. You need bundletool to build a new set of installable APKs from your app's bundle.
• Make sure your app is using Play Core 1.7.2 or higher. To learn more, see Include the Play Core Library in your project.

Note: Play Core Library currently doesn’t support module uninstalls or deferred installs. To test this functionality, consider using internal app sharing.

Build a set of APKs

If you haven't already done so, build your app’s split APKs, as follows:

1. Build an app bundle for your app using one of the following methods:
   • Use Android Studio and the Android plugin for Gradle to build and sign an Android App Bundle.
   • Build your app bundle from the command line.

2. Use bundletool to generate a set of APKs for all device configurations with the following command:

   bundletool build-apks --local-testing
     --bundle my_app.aab
     --output my_app.apks
   

The --local-testing flag includes meta-data in your APKs' manifests that lets the Play Core library know to use the local split APKs to test installing feature modules, without connecting to the Play Store.

Deploy your app to the device

After you build a set of APKs using the --local-testing flag, use bundletool to install the base version of your app and transfer additional APKs to your device's local storage. You can perform both actions with the following command:

bundletool install-apks --apks my_app.apks

Now, when you start your app and complete the user flow to download and install a feature module, the Play Core Library uses the APKs that bundletool transferred to the device's local storage.

Simulate a network error

To simulate module installs from the Play Store, the Play Core Library uses an alternative to the SplitInstallManager, called FakeSplitInstallManager, to request the module. When you use bundletool with the --local-testing flag to build a set of APKs and deploy them to your test device, it includes metadata that instructs the Play Core Library to automatically switch your app's API calls to invoke FakeSplitInstallManager, instead of SplitInstallManager.

FakeSplitInstallManager includes a boolean flag that you can enable to simulate a network error the next time your app requests to install a module. To access FakeSplitInstallManager in your tests, you can get an instance of it using the FakeSplitInstallManagerFactory, as shown below:

Kotlin

// Creates an instance of FakeSplitInstallManager with the app's context.
val fakeSplitInstallManager = FakeSplitInstallManagerFactory.create(context)
// Tells Play Core Library to force the next module request to
// result in a network error.
fakeSplitInstallManager.setShouldNetworkError(true)

Java

// Creates an instance of FakeSplitInstallManager with the app's context.
FakeSplitInstallManager fakeSplitInstallManager =
    FakeSplitInstallManagerFactory.create(context);
// Tells Play Core Library to force the next module request to
// result in a network error.
fakeSplitInstallManager.setShouldNetworkError(true);