Android Testing Support Library 1.0 is here!

Posted by Michael Amygdalidis, Stephan Linzner and Nick Korostelev from the Mobile-Ninjas team at Google

We're pleased to announce the version 1.0 release of the Android Testing Support Library (ATSL).

ATSL version 1.0 is a major update to our existing testing APIs and comes with lots of new features, improved performance, stability, and bug fixes. It provides full API parity with the now deprecated Android platform testing APIs. This release also adds a number of features that we discussed in our Google I/O 2017 talk, such as native support for Multiprocess Espresso and the Android Test Orchestrator.

We are also happy to announce that, starting with version 1.0, we're distributing releases on Google's Maven repository, which makes it a lot easier to use ATSL in your builds. To learn more about using this repository, see the getting started with the Google Maven repository guide. Note that we're no longer tying future updates to the testing infrastructure with platform updates. If you have not yet upgraded your tests to ATSL, this is an excellent time.

Finally, we want to announce a big update to our Android testing documentation. We've migrated our old testing documentation from our GitHub website to http://ift.tt/2eIvwnm. All the testing documentation now appears in a single place, making it even easier to learn how to write and execute tests on Android.

Let's move on to the fun part of this post, an overview of new APIs and tools that we're providing in this release.

Espresso Improvements

Espresso 3.0.0 comes with amazing new features and improved overall performance. Some of the highlights include: Multiprocess Espresso, Idling Registry and new Idling Resources. Let's dive in and have a more detailed look at these new features:

Multiprocess Espresso

Starting with Android O, the platform includes support for instrumenting tests outside of your app's default process. (Prior to Android O, you could only test against app components in your app's default process.) Multiprocess Espresso makes this support possible. It allows you to seamlessly test your app's UI interactions that cross process boundaries while still maintaining Espresso's synchronization guarantees.

The good news is that Espresso does all the work; you don't have to change anything for setups with UI in multiple processes. You can keep writing your Espresso tests like you would for single process apps, and Espresso automatically handles the process IPC and synchronization between processes.

The following diagram shows how multiple instances of Espresso communicate with each other:

If you want to learn more about Multiprocess Espresso and how to use it, please take a look at our documentation and our Multiprocess sample.

Idling Registry

Some apps use build flavors in Gradle or a dependency injection framework, like Dagger, to generate test build configurations that register idling resources. Others simply expose the idling resource through their activities. The problem with all these approaches is that they add complexity to your development workflow, and some of them even break encapsulation. With the latest release of Espresso, we've made it easier to register idling resources from within your app code by introducing the new IdlingRegistry API. IdlingRegistry is a lightweight registry that doesn't bring in the entire Espresso library, so you can more easily register resources from your application code. When combining this API with Multiprocess Espresso, you can register idling resources from any process within your application code.

Registration from the Espresso class is now deprecated.

Idling Resources

Writing custom idling resources can be time consuming, so Espresso 3.0.0 now comes with more idling resources out of the box to synchronize your threads. The new resources include: IdlingThreadPoolExecutor and IdlingScheduledThreadPoolExecutor. There will be more to come!

To take advantage of the new idling resource, add these new dependencies to your build.gradle file:

  androidTestCompile "com.android.support.test.espresso.idling:idling-concurrent:3.0.0"

Additionally, CountingIdlingResource, which was previously deprecated in Espresso contrib, has been removed with this release. Therefore, you need to update your tests to use the new CountingIdlingResource package that's located in Espresso idling resource. For the full migration details, refer to our release notes.

ProviderTestRule

When you test ContentProvider objects, you can now use ProviderTestRule instead of ProviderTestCase2. ProviderTestRule offers an easier way to work with other test rules currently available for AndroidJUnit4.

ProviderTestRule includes APIs for initialization, as well as commands to run against a ContentProvider under test. If your ContentProvider is based off of a SQLite database, you can use the ProviderTestRule commands for setting the database file and initialization commands.

To learn more, see the ProviderTestRule documentation.

Grant Permission Rule

Android M (API level 23) allows apps to request permissions at runtime. However, the dialogs that request runtime permissions place tests in a state where they cannot continue, causing them to fail. By using GrantPermissionRule, you can skip the dialog popups altogether and simulate a user granting a runtime permission for your app.

Android Test Orchestrator

Typically, AndroidJUnitRunner runs all tests in the same instrumentation process, which can cause a number of problems. For example, tests share their state in memory, and if one test crashes, it prevents the remainder of the test suite from running.

Although it's possible to isolate tests by issuing sequential adb commands, this process adds host-side processing load. By using the new Android Test Orchestrator instead, you can achieve test isolation entirely on the device, as shown in this diagram:

Be aware that if your tests require shared state to pass, the orchestrator causes them to fail. This behavior is by design. As of this post, Android Test Orchestrator is in beta and is available for use via the command line. We have integrations planned for Firebase Test Lab and Android Studio, coming soon.

For more information, see the Android Testing Orchestrator developer guide.

AndroidJUnitRunner

AndroidJUnitRunner now includes a number of additional features:

You can use JUnitParams.
You can configure class loaders and custom JUnit test filters using the runner arguments

Sometimes you want to test an activity that you create and configure on the fly as part of your test workflow. Now, you can configure MonitoringInstrumentation (and by extension, AndroidJUnitRunner) using an InterceptingActivityFactory. You can create your activity under test with a test-specific configuration without having to rely on compile-time injection.

This overview highlights only some of the most significant changes that we've made to ATSL. They are many more changes that are worth exploring. For the full release details, refer to our release notes.

Last but not least, we want to thank all the developers who contributed features to this release. We also want to thank the Android testing experts on the mobile engineering teams at American Express, Slack and GDE Chiu-Ki Chan for collaborating with us and providing valuable feedback on the pre-release version of Android Testing Support Library.

Happy testing from the ATSL team!