Firebase Test Lab provides cloud-based infrastructure for testing Android apps, including full integration with the gcloud command-line interface (CLI). This document covers the installation and configuration required to get started using Test Lab from the gcloud CLI.
For a complete list of gcloud
commands you can use
with your Android app in Test Lab, visit the
reference documentation for gcloud firebase test android
.
If you don't have a Firebase project for your app, go to the Firebase console and click Create New Project to create one now. You will need ownership or edit permissions in your project.
Set up the gcloud CLI
- Download the Google Cloud SDK.
- Make sure your installation is up-to-date:
gcloud components update
- Log in to the gcloud CLI using your Google account:
gcloud auth login
- Set your Firebase project in gcloud, where PROJECT_ID is
the ID of your Firebase project:
gcloud config set project PROJECT_ID
This includes the gcloud CLI tool.
Configure your test
In this example, you will run some tests on a simple note-taking Android app called Notepad.
Download the binary APK file for the Notepad app (app-debug-unaligned.apk) and its corresponding instrumentation tests (app-debug-test-unaligned.apk) provided in the NotePad/app/build/outputs/apk/ directory of notepad.zip.
Get the current list of Android devices available to test against, as follows:
$ gcloud firebase test android models list
The first column of the command output,
MODEL_ID
, contains the identifier that you can use later to run tests on a specific model. TheOS_VERSION_ID
column lists the operating system versions supported by that device. If you don't specify whichMODEL_ID
(s) to test against, the default noted under theTAGS
column is used.Learn more about a specific Android
MODEL_ID
with thefirebase test android models describe
command, as follows:
The example command shown above provides detailed information about the$ gcloud firebase test android models describe Nexus5
Nexus5
model, including the brand, manufacturer, and supported API levels, and whether the model is physical or virtual.Get the current list of Android OS versions available to test against:
$ gcloud firebase test android versions list
You can use an identifier from either of the first two columns of command output (
OS_VERSION_ID
andVERSION
), to later run tests against an Android OS version. If you don't specify the Android OS versions to test against, the default noted under theTAGS
column is used.Get the current list of locales available to test against:
The first column of the command output,$ gcloud firebase test android locales list
LOCALE
, contains the identifier that you can use later to run tests against a locale. If you don't specify the locales to test against, English is used as the default locale. Command output is not shown here because hundreds of locales are available.
Running tests
Now that you know the range of device models, OS versions, and locales available
to use when testing your app, you can use that information to specify test
devices using the gcloud firebase test android run
command and the --device
flag. This command and flag are used whether you are using the Robo test to
automatically test your app, or whether you are running instrumentation tests
written specifically to test your app.
Running the Robo test
Even if you don't have any instrumentation tests, you can still look for bugs in your app. Use the Robo test to perform automated review of your app's user interface. Robo test exercises the app by performing a static analysis of the various paths through the app's user interface, and then crawling through the app to find crashes and other potential issues.
Let's start by running an example command:
gcloud firebase test android run \ --type robo \ --app app-debug-unaligned.apk \ --device model=Nexus6,version=21,locale=en,orientation=portrait \ --device model=Nexus7,version=19,locale=fr,orientation=landscape \ --timeout 90s
The --type robo
parameter is implicit if no --type
value is specified.
You can see the complete set of command line options for running tests by
typing: gcloud help firebase test android run
.
As an alternative to specifying all these arguments on the command line,
you can optionally specify your arguments in a YAML-formatted argument file.
Run gcloud topic arg-files
to learn how to use this feature.
See the Analyze your test results section to learn how to investigate the test results from the Robo test.
Running your instrumentation tests
Now use the gcloud
command line tool to run the Notepad app's
Espresso
tests on your specified Android device configurations, using the
instrumentation
test type to run the tests in app-debug-test-unaligned.apk
as follows:
gcloud firebase test android run \ --type instrumentation \ --app app-debug-unaligned.apk \ --test app-debug-test-unaligned.apk \ --device model=Nexus6,version=21,locale=en,orientation=portrait \ --device model=Nexus7,version=19,locale=fr,orientation=landscape
The --type instrumentation
parameter is implicit if a test APK has been
specified with --test
. As an alternative to specifying all these arguments on
the command line, you can optionally specify your arguments in a YAML-formatted
argument file. Run gcloud topic arg-files
to learn how to use this feature.
The gcloud CLI supports Android Test Orchestrator.
Orchestrator requires AndroidJUnitRunner v1.0 or higher. To enable it, use
gcloud firebase test android run
with the --use-orchestrator
flag. To disable it use the --no-use-orchestrator
flag.
Note: You can also control how Test Lab runs your instrumentation tests
using additional flags that are not shown above. For example, you can use the
--test-targets
flag to test a single class or a class method used by your test
APK. You can also find out whether your test that failed was actually flaky or
not by using '--num-flaky-test-attempts' flag, which specifies the number of
times a test execution should be re-attempted if one or more of its test cases
fail for any reason. To learn more, see gcloud firebase test android run.
Code coverage reports for instrumentation tests
Test Lab supports code coverage reporting tools
EMMA and
JaCoCo. If you have either tool integrated
into the build for your app, you can get a code coverage report for Test Lab
tests by running the gcloud firebase test android run
command with the
following arguments:
gcloud firebase test android run \ --type instrumentation \ --app your-app.apk \ --test your-app-test.apk \ --device model=TestDevice,version=AndroidVersion \ --environment-variables coverage=true,coverageFile="/sdcard/coverage.ec" \ --directories-to-pull /sdcard
When Test Lab finishes running your tests, find your code coverage reports in Google Cloud Storage:
- Open the Firebase console link that the
gcloud
tool printed above the test result table in your terminal. - Click a test execution from the list at that link to open that execution's details page.
- Click Test results to go to the Cloud Storage bucket with that execution's test results.
- Open
artifacts/coverage.ec
to see your code coverage report.
Analyze your test results
After a few minutes, a basic summary of your test results is printed by the gcloud tool:
The output of your command line test run also includes a link to view test results. To learn more about how to interpret these results, see Analyzing Firebase Test Lab for Android Results.
Custom login and text input with Robo test
Robo test automatically completes sign-in screens that use a Google account
for authentication, unless you use the
--no-auto-google-login
parameter. It can also complete custom login screens using test account
credentials that you provide. You can also use this parameter to provide custom
input text for other text fields used by your app.
To complete text fields in your app, use the
--robo-directives
parameter and provide a comma-separated list of key-value
pairs, where the
key
is the Android resource name of the target UI element, and the value
is
the text string. You can also use this flag to tell Robo to ignore specific
UI elements (e.g., "logout" button).
EditText
fields are supported but not text fields in WebView
UI elements.
For example, you could use the following parameter for custom login:
--robo-directives username_resource=username,password_resource=password
Available commands and flags
The Test Lab gcloud CLI has several commands and flags available that let you run tests with different specifications:
Android Test Orchestrator flag: A flag to enable Orchestrator, a tool that allows you to run each of your app's tests in its own invocation of
Instrumentation
. Test Lab always runs the latest version of Orchestrator.Game Loop test flags: A set of config flags that enable and control a "demo mode" to simulate player actions in game apps. Learn more about running Game Loop tests with Test Lab.
Uniform Sharding flag (in beta): A flag that specifies the number of shards into which you want to evenly distribute test cases. The shards are run in parallel on separate devices.
Manual Sharding flag (in beta): A flag that specifies a group of packages, classes, and/or test cases to run in a shard (a group of test cases). The shards are run in parallel on separate devices.
Network traffic profiles flag (in beta): A flag that specifies which network profile your tests use with physical devices. Network profiles emulate a variety of networks conditions, allowing you to test your app's performance on unreliable or unpredictable networks.
Scripting gcloud commands with Test Lab
You can use shell scripts or batch files to automate mobile app testing commands that you would otherwise run using the gcloud command line. The following example bash script runs an instrumentation test with a two-minute timeout, and reports if the test run completed successfully:
if gcloud firebase test android run --app my-app.apk --test my-test.apk --timeout 2m then echo "Test matrix successfully finished" else echo "Test matrix exited abnormally with non-zero exit code: " $? fi
Script exit codes
Test Lab provides several exit codes that you can use to better understand the results of tests that you run using scripts or batch files.
Scripting exit codes for Test Lab
Exit code | Notes |
---|---|
0 | All test executions passed. |
1 | A general failure occurred. Possible causes include: a filename that does not exist or an HTTP/network error. |
2 | Testing exited because unknown commands or arguments were provided. |
10 | One or more test cases (tested classes or class methods) within a test execution did not pass. |
15 | Firebase Test Lab could not determine if the test matrix passed or failed, because of an unexpected error. |
18 | The test environment for this test execution is not supported because of incompatible test dimensions. This error might occur if the selected Android API level is not supported by the selected device type. |
19 | The test matrix was canceled by the user. |
20 | A test infrastructure error occurred. |