.TH "GCLOUD_BETA_TOPIC_ARG\-FILES" 1



.SH "NAME"
.HP
gcloud beta topic arg\-files \- supplementary help for arg\-files to be used with \fBgcloud firebase test\fR



.SH "DESCRIPTION"

\fB(BETA)\fR Supplementary help for arg\-files to be used with \fBgcloud
firebase test\fR.

All \fBgcloud firebase test android run\fR arguments may be specified by flags
on the command line and/or via a YAML\-formatted \fIARG_FILE\fR. The optional,
positional ARG_SPEC argument on the command line is used to specify a single
\fIARG_FILE\fR:\fIARG_GROUP_NAME\fR pair, where \fIARG_FILE\fR is the path to
the YAML argument file, and \fIARG_GROUP_NAME\fR is the name of the argument
group to load and parse. The \fIARG_FILE\fR must contain valid YAML syntax or
gcloud will respond with an error.

The basic format of a YAML argument file is:

.RS 2m
arg\-group1:
  arg1: value1  # a comment
  arg2: value2
  ...
.RE

.RS 2m
# Another comment
arg\-group2:
  arg3: value3
  ...
.RE

List arguments may be specified within square brackets:

.RS 2m
directories\-to\-pull: [/sdcard/dir1, /data/dir2]
.RE

or by using the alternate YAML list notation with one dash per list item:

.RS 2m
directories\-to\-pull:
  \- /sdcard/dir1
  \- /data/dir2
.RE

If a list argument only contains a single value, you may omit the square
brackets:

.RS 2m
directories\-to\-pull: /sdcard/dir1
.RE

Composition

A special \fBinclude: [\fIARG_GROUP1\fR, ...]\fR syntax allows merging or
composition of argument groups (see \fBEXAMPLES\fR below). Included argument
groups can \fBinclude:\fR other argument groups within the same YAML file, with
unlimited nesting.

Precedence

An argument which appears on the command line has the highest precedence and
will override the same argument if it is specified within an argument file.

Any argument defined directly within a group will have higher precedence than an
identical argument which is merged into that group using the \fBinclude:\fR
keyword.



.SH "EXAMPLES"

Here are the contents of a very simple YAML argument file which is assumed to be
stored in a file named excelsior_args.yaml:

.RS 2m
# Run a quick 'robo' test on the 'Excelsior' app for
# 90 seconds using only the default Test Lab device.
quick\-robo\-test:
  app: path/to/excelsior.apk
  type: robo
  max\-steps: 100
  timeout: 90s
  async: true
.RE

To invoke this test, run:

.RS 2m
$ gcloud firebase test android run \e
    excelsior_args.yaml:quick\-robo\-test
.RE

To select which device(s) you wish to test against in an argument file, use
\fBdevice:\fR to specify one or more devices, with each device having one or
more dimensions. For example, to specify the LG G3 device in the Chinese locale
and with landscape orientation, use:

.RS 2m
single\-device\-group:
  device: [{model: g3, orientation: landscape, locale: zh}]
.RE

To specify multiple devices, use any of the following equivalent YAML formats:

.RS 2m
multi\-device\-group1:
  device: [{model: flo}, {model: g3, version: 19, locale: zh}, {model: mako, version: 21}]
.RE

.RS 2m
multi\-device\-group2:
  device:
    \- {model: flo}
    \- {model: g3, version: 19, locale: zh}
    \- {model: mako, version: 21}
.RE

.RS 2m
multi\-device\-group3:
  device:
    \- model: flo
    \- model: g3
      version: 19
      locale: zh
    \- model: mako
      version: 21
.RE

If your app has a login screen, or has additional UI elements which require
input text, you may specify the resource names of the Android target UI
elements, along with their corresponding input values, in the 'robo\-directives'
map argument. You may also specify the elements which the Robo test should
prioritize clicking. In the example below, "username_resource" is the resource
name of the username field and "username" is the input for that field (similarly
for password), and "signin_button_resource" is the resource name of the sign in
button.

.RS 2m
# Run a 'robo' test on the 'Excelsior' app with login credentials.
robo\-test\-with\-login:
  app: path/to/excelsior.apk
  type: robo
  robo\-directives:
    "text:username_resource": username
    "text:password_resource": password
    "click:sigin_button_resource": ""
.RE

Assuming the above YAML text is appended to the arg\-file named
excelsior_args.yaml, you may invoke the test by running:

.RS 2m
$ gcloud firebase test android run \e
    excelsior_args.yaml:robo\-test\-with\-login
.RE

Here is a slightly more complicated example which demonstrates composition of
argument groups using the legacy device dimension arguments (\fBdevice:\fR is
now the preferred way to specify test devices). Assume the following YAML text
is appended to the arg\-file shown above named excelsior_args.yaml:

.RS 2m
# Specify some unit tests to be run against a test matrix
# with one device type, two Android versions, and four
# locales, for a total of eight test variations (1*2*4).
unit\-tests:
  type: instrumentation
  app: path/to/excelsior.apk
  test: path/to/excelsior\-test.apk  # the unit tests
  timeout: 10m
  device\-ids: NexusLowRes
  include: [supported\-versions, supported\-locales]
.RE

.RS 2m
supported\-versions:
  os\-version\-ids: [21, 22]
.RE

.RS 2m
supported\-locales:
  locales: [en, es, fr, it]
.RE

To invoke this test matrix, run:

.RS 2m
$ gcloud firebase test android run excelsior_args.yaml:unit\-tests
.RE

To run these unit tests with the same locales and os\-version\-ids, but
substituting a sampling of three physical Android devices instead of the single
virtual NexusLowRes device, run:

.RS 2m
$ gcloud firebase test android run excelsior_args.yaml:unit\-tests \e
    \-\-device\-ids shamu,htc_m8,g3
.RE

In the last example, the \-\-device\-ids argument on the command line overrides
the device\-ids: specification inside the arg\-file because command\-line
arguments have higher precedence.



.SH "NOTES"

This command is currently in beta and might change without notice. These
variants are also available:

.RS 2m
$ gcloud topic arg\-files
.RE

.RS 2m
$ gcloud alpha topic arg\-files
.RE