This guide describes how to prepare and run an instrumentation test usingFirebase Test Lab. To use this guide, you'll need aninstrumentation test (written by you or your team) that uses theEspresso orUI Automator Android test frameworks. Instrumentation tests can run up to 45minutes on physical devices and up to 60 minutes onvirtual devices.

In the steps later, you'll upload your app's APK andyour test's APK to Firebase.

Firebase Test Lab includes a library (testlab-instr-lib) that you canuse to process any screenshots you take with AndroidX’sScreenCapture when running instrumentation tests, such as tests written using theEspresso test framework.This section describes how to createScreenCapture objects with the AndroidXlibrary and how to process them using testlab-instr-lib.

After your instrumentation test has run, you can view the captured screenshotsin theFirebase console.

Try out a sample app

Download theNotePad sample app to try out this functionality. The ability to take screenshots is alreadyincorporated into the NotePad project.

Step 1. Add the screenshot library to your project

1. In your test project'sroot-level settings Gradle file(settings.gradle.kts orsettings.gradle), add Google's Maven repositoryto everyrepositories section:

   pluginManagement{repositories{// Add the following line:google()// Google's Maven repositorymavenCentral()gradlePluginPortal()}}dependencyResolutionManagement{repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)repositories{// Add the following line:google()// Google's Maven repositorymavenCentral()}}// ...

2. In yourmodule (app-level) Gradle file (usually<project>/<app-module>/build.gradle.kts or<project>/<app-module>/build.gradle), add a dependency for theTest Lab screenshot library.

   dependencies{// ...// Add Test Lab's instrumentation test screenshot library:androidTestImplementation("com.google.firebase:testlab-instr-lib:0.2")// ...

3. In your test'sAndroidManifest.xml file, register theFirebaseScreenCaptureProcessor in a meta-data tag within the<instrumentation> element. You can also specify the processor as anargument in AndroidJUnitRunner instead (see theAndroidJUnitRunner reference documentation for instructions on how).

   <instrumentation// Check that you have the following line (if not, add it):android:name="androidx.test.runner.AndroidJUnitRunner"// Specifies AndroidJUnitRunner as the test runnerandroid:targetPackage="com.your.package.name">// Add the following:<meta-dataandroid:name="screenCaptureProcessors"android:value="com.google.firebase.testlab.screenshot.FirebaseScreenCaptureProcessor"/></instrumentation>...

4. In your app'sAndroidManifest.xml file, add the following lines within the<manifest> element:

    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

5. In yourAndroidManifest.xml file, specify system permissions for your appby adding the following lines within the<manifest> tag. If you're testingonAndroid 10 (API level 29) or higher, omit theWRITE_EXTERNAL_STORAGEpermission (your app does not require this permission in order to read andwrite screenshots to the device).

   <manifest ... >    <!-- WRITE_EXTERNAL_STORAGE is not needed on Android 10 (API level 29) or higher. -->    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>    <uses-permission android:name="android.permission.INTERNET"/>    ...</manifest>

Step 2. Take screenshots during your test

At any point in your test where you want to take a screenshot, call theScreenshot.capture() method from the AndroidX library. This produces aScreenCapture object.When you callprocess() on theScreenCapture object, it gets processedusing theScreenCaptureProcessor that's registered in yourAndroidManifest.xml. Note that theBasicScreenCaptureProcessor is used if no processors are registered.Since you registered theFirebaseScreenCaptureProcessor, your screenshots willbe processed viaFirebaseScreenCaptureProcessor and will be availablefor you with your results when you run your test withFirebase Test Lab.

Example use cases for creating aScreenCapture:

• Take a full ScreenCapture on a API Build.VERSION_CODES.JELLY_BEAN_MR2 andabove:

  Screenshot.capture()

• Take aScreenCapture of the Activity on any API level. Note this is theonly option for devices that are below Build.VERSION_CODES.JELLY_BEAN_MR2.

  @RulepublicActivityTestRule<MainActivity>activityRule=newActivityTestRule<>(MainActivity.class);...Screenshot.capture(activityRule.getActivity());...

Example use cases for processing a ScreenCapture

• Process aScreenCapture via theFirebaseScreenCaptureProcessor:

  Screenshot.capture().process();

• Process aScreenCapture via a specifiedScreenCaptureProcessor(this allows you to skip registering the processor):

  Set<ScreenCaptureProcessor> processors = new HashSet<>();processors.add(new FirebaseScreenCaptureProcessor());Screenshot.capture().process(processors);

• Set the name and format of theScreenCapture and process it using theregistered processor:

  Screenshot.capture().setName("myscreenshot").setFormat(CompressFormat.JPEG).process();

Step 3. Build and run your test

1. Build your app and test APKs (seeTest your app for instructions).

2. Upload the APK files to theTest Lab dashboardof theFirebase console.

3. Finally, run your test.

Step 4. View your test screenshots

After your test has completed, you can view any screenshots taken in theFirebase console.

1. In theTests tab, select your completed test,then click theResults tab.

2. Select your test again, then click theScreenshots tab that appears.

(Optional) Enable additional test features

You can enable the following features in your test before running it withTest Lab:

Enable Orchestrator

Android Test Orchestrator is a tool that runs each of your app's instrumentation tests independently.Test Lab always uses the latest version of Orchestrator.

To enable Orchestrator forTest Lab, ininstrumentation testsetup,clickAdditional options >Run with Orchestrator.

Keep in mind that when you use Orchestrator, each test runs its owninstrumentation instance, which means that the app process is restarted afterevery test case. The resulting increased run times might impact yourquota usage or billed time and mightcause you to exceed your devices' timeout limits. If you reduce your app'sstartup time, this overhead will shorten.

To set additional options for Orchestrator, specify them viaenvironmentVariables field. For example, to useclearPackageData, use thisoption in gcloud:

--environment-variablesclearPackageData=true

Enable sharding

Test sharding divides a set of tests into sub-groups (shards) that runseparately in isolation.Test Lab automatically runs each shard in parallelusing multiple devices, and completes the entire set of tests in less time.

For example, if you create N shards, for each device you select,Test Lab spins up Nidentical devices and runs a subset of the tests on each device. This meansthat sharded test cases can result in multiple test executions per device.Non-sharded test cases, however, result in one test execution perdevice. To learnTest Lab concepts, seeKey concepts.

To enable test sharding in theFirebase console, follow these steps:

1. Ininstrumentation test setup,clickAdditional options.

2. In theSharding section, enter the number of shards you want to run.

Billing for test shards

Test Lab implements your shards by leveragingAndroidJUnitRunner's built-insharding mechanism. To avoid being charged for spinning up empty shards (shards without assignedtest cases), the number of shards youcreate should be less than the total number of test cases. Depending on howlong each test case takes to run, it's typically a good idea to assign 2-10 testcases per shard.

For more information on billing, readUsage, quotas, and billing.