.TH "GCLOUD_ALPHA_FIREBASE_TEST_IOS_RUN" 1



.SH "NAME"
.HP
gcloud alpha firebase test ios run \- invoke a test in Firebase Test Lab for iOS and view test results



.SH "SYNOPSIS"
.HP
\f5gcloud alpha firebase test ios run\fR [\fIARGSPEC\fR] [\fB\-\-device\fR=\fIDIMENSION\fR=\fIVALUE\fR,[...]] [\fB\-\-test\fR=\fIXCTEST_ZIP\fR] [\fB\-\-timeout\fR=\fITIMEOUT\fR] [\fB\-\-type\fR=\fITYPE\fR] [\fB\-\-xcode\-version\fR=\fIXCODE_VERSION\fR] [\fB\-\-xctestrun\-file\fR=\fIXCTESTRUN_FILE\fR] [\fB\-\-additional\-ipas\fR=\fIIPA\fR,[\fIIPA\fR,...]] [\fB\-\-app\fR=\fIAPP\fR] [\fB\-\-async\fR] [\fB\-\-client\-details\fR=[\fIKEY\fR=\fIVALUE\fR,...]] [\fB\-\-directories\-to\-pull\fR=[\fIDIR_TO_PULL\fR,...]] [\fB\-\-num\-flaky\-test\-attempts\fR=\fIint\fR] [\fB\-\-other\-files\fR=\fIDEVICE_PATH\fR=\fIFILE_PATH\fR,[...]] [\fB\-\-record\-video\fR] [\fB\-\-results\-bucket\fR=\fIRESULTS_BUCKET\fR] [\fB\-\-results\-dir\fR=\fIRESULTS_DIR\fR] [\fB\-\-results\-history\-name\fR=\fIRESULTS_HISTORY_NAME\fR] [\fB\-\-robo\-script\fR=\fIROBO_SCRIPT\fR] [\fB\-\-scenario\-numbers\fR=\fIint\fR,[\fIint\fR,...]] [\fB\-\-test\-special\-entitlements\fR] [\fB\-\-filter\fR=\fIEXPRESSION\fR] [\fB\-\-limit\fR=\fILIMIT\fR] [\fB\-\-page\-size\fR=\fIPAGE_SIZE\fR] [\fB\-\-sort\-by\fR=[\fIFIELD\fR,...]] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

\fB(ALPHA)\fR \fBgcloud alpha firebase test ios run\fR invokes and monitors
tests in Firebase Test Lab for iOS.

Two types of iOS tests are currently supported:
.RS 2m
.IP "\(bu" 2m
\fBxctest\fR: corresponds to the XCTest and XCUITest frameworks. Other iOS
testing frameworks which are built upon XCTest and XCUITest should also work.
The XCTEST_ZIP test package is a zip file built using Apple's Xcode and
supporting tools. For a detailed description of the process to create your
XCTEST_ZIP file, see
https://firebase.google.com/docs/test\-lab/ios/command\-line.
.IP "\(bu" 2m
\fBgame\-loop\fR: launches the game app through a custom URL scheme to execute a
"demo mode" built into the game app that simulates actions of a real player.
This test type can include multiple game loops (also called "scenarios")
indicated by positive numbers.
.RE
.sp

The type of test to run can be specified with the \fB\-\-type\fR flag, which
defaults to \f5xctest\fR.

All arguments for \fBgcloud alpha firebase test ios run\fR may be specified on
the command line and/or within an argument file. Run \fB$ gcloud topic
arg\-files\fR for more information about argument files.



.SH "EXAMPLES"

To help you identify and locate your test matrix in the Firebase console, run:

.RS 2m
$ gcloud alpha firebase test ios run \-\-test=XCTEST_ZIP \e
    \-\-client\-details=matrixLabel="Example matrix label"
.RE

To invoke an XCTest lasting up to five minutes against the default device
environment, run:

.RS 2m
$ gcloud alpha firebase test ios run \-\-test=XCTEST_ZIP \-\-timeout=5m
.RE

To invoke an XCTest against an iPad 5 running iOS 11.2, run:

.RS 2m
$ gcloud alpha firebase test ios run \-\-test=XCTEST_ZIP \e
    \-\-device=model=ipad5,version=11.2
.RE

To run your tests against multiple iOS devices simultaneously, specify the
\fB\-\-device\fR flag more than once:

.RS 2m
$ gcloud alpha firebase test ios run \-\-test=XCTEST_ZIP \e
    \-\-device=model=iphone7 \-\-device=model=ipadmini4,version=11.2 \e
    \-\-device=model=iphonese
.RE

To run your XCTest using a specific version of Xcode, say 9.4.1, run:

.RS 2m
$ gcloud alpha firebase test ios run \-\-test=XCTEST_ZIP \e
    \-\-xcode\-version=9.4.1
.RE

To help you identify and locate your test matrix in the Firebase console, run:

.RS 2m
$ gcloud alpha firebase test ios run \-\-test=XCTEST_ZIP \e
    \-\-client\-details=matrixLabel="Example matrix label"
.RE

To run an iOS game loop, specify the \fB\-\-type\fR and \fB\-\-app\fR flags:

.RS 2m
$ gcloud alpha firebase test ios run \-\-type=game\-loop \-\-app=app.ipa
.RE

To run an iOS game loop with specific scenario(s), use the
\fB\-\-scenario\-numbers\fR flag:

.RS 2m
$ gcloud alpha firebase test ios run \-\-type=game\-loop \e
    \-\-app=app.ipa \-\-scenario\-numbers=1,2,3
.RE

To run a test that pushes a local file onto the device before testing, use the
\fB\-\-other\-files\fR flag:

.RS 2m
$ gcloud alpha firebase test ios run \-\-type=game\-loop \e
    \-\-app=app.ipa \-\-scenario\-numbers=1 \e
    \-\-other\-files=/private/var/mobile/Media/file.txt=/path/to/\e
file.txt
.RE

All test arguments for a given test may alternatively be stored in an argument
group within a YAML\-formatted argument file. The \fIARG_FILE\fR may contain one
or more named argument groups, and argument groups may be combined using the
\f5include:\fR attribute (Run \fB$ gcloud topic arg\-files\fR for more
information). The ARG_FILE can easily be shared with colleagues or placed under
source control to ensure consistent test executions.

To run a test using arguments loaded from an ARG_FILE named
\fBexcelsior_app_args\fR, which contains an argument group named
\fBios\-args:\fR, use the following syntax:

.RS 2m
$ gcloud alpha firebase test ios run \e
    path/to/excelsior_app_args:ios\-args
.RE



.SH "POSITIONAL ARGUMENTS"

.RS 2m
.TP 2m
[\fIARGSPEC\fR]

An ARG_FILE:ARG_GROUP_NAME pair, where ARG_FILE is the path to a file containing
groups of test arguments in yaml format, and ARG_GROUP_NAME is the particular
yaml object holding a group of arg:value pairs to use. Run \fB$ gcloud topic
arg\-files\fR for more information and examples.


.RE
.sp

.SH "COMMONLY USED FLAGS"

.RS 2m
.TP 2m
\fB\-\-device\fR=\fIDIMENSION\fR=\fIVALUE\fR,[...]

A list of \f5\fIDIMENSION=VALUE\fR\fR pairs which specify a target device to
test against. This flag may be repeated to specify multiple devices. The device
dimensions are: \fBmodel\fR, \fBversion\fR, \fBlocale\fR, and \fBorientation\fR.
If any dimensions are omitted, they will use a default value. The default value,
and all possible values, for each dimension can be found with the
\f5\fIlist\fR\fR command for that dimension, such as \f5$ gcloud alpha firebase
test ios models list\fR. Omitting this flag entirely will run tests against a
single device using defaults for every dimension.

Examples:

.RS 2m
\-\-device model=iphone8plus
\-\-device version=11.2
\-\-device model=ipadmini4,version=11.2,locale=zh_CN,orientation=landscape
.RE

.TP 2m
\fB\-\-test\fR=\fIXCTEST_ZIP\fR

The path to the test package (a zip file containing the iOS app and XCTest
files). The given path may be in the local filesystem or in Google Cloud Storage
using a URL beginning with \f5gs://\fR. Note: any .xctestrun file in this zip
file will be ignored if \fB\-\-xctestrun\-file\fR is specified.

.TP 2m
\fB\-\-timeout\fR=\fITIMEOUT\fR

The max time this test execution can run before it is cancelled (default: 15m).
It does not include any time necessary to prepare and clean up the target
device. The maximum possible testing time is 45m on physical devices and 60m on
virtual devices. The \fITIMEOUT\fR units can be h, m, or s. If no unit is given,
seconds are assumed. Examples:
.RS 2m
.IP "\(em" 2m
\fB\-\-timeout 1h\fR is 1 hour
.IP "\(em" 2m
\fB\-\-timeout 5m\fR is 5 minutes
.IP "\(em" 2m
\fB\-\-timeout 200s\fR is 200 seconds
.IP "\(em" 2m
\fB\-\-timeout 100\fR is 100 seconds
.RE
.sp

.TP 2m
\fB\-\-type\fR=\fITYPE\fR

The type of iOS test to run. \fITYPE\fR must be one of: \fBxctest\fR,
\fBgame\-loop\fR, \fBrobo\fR.

.TP 2m
\fB\-\-xcode\-version\fR=\fIXCODE_VERSION\fR

The version of Xcode that should be used to run an XCTest. Defaults to the
latest Xcode version supported in Firebase Test Lab. This Xcode version must be
supported by all iOS versions selected in the test matrix. The list of Xcode
versions supported by each version of iOS can be viewed by running \f5$ gcloud
alpha firebase test ios versions list\fR.

.TP 2m
\fB\-\-xctestrun\-file\fR=\fIXCTESTRUN_FILE\fR

The path to an .xctestrun file that will override any .xctestrun file contained
in the \fB\-\-test\fR package. Because the .xctestrun file contains environment
variables along with test methods to run and/or ignore, this can be useful for
customizing or sharding test suites. The given path may be in the local
filesystem or in Google Cloud Storage using a URL beginning with \f5gs://\fR.


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-additional\-ipas\fR=\fIIPA\fR,[\fIIPA\fR,...]

List of up to 100 additional IPAs to install, in addition to the one being
directly tested. The path may be in the local filesystem or in Google Cloud
Storage using gs:// notation.

.TP 2m
\fB\-\-app\fR=\fIAPP\fR

The path to the application archive (.ipa file) for game\-loop testing. The path
may be in the local filesystem or in Google Cloud Storage using gs:// notation.
This flag is only valid when \fB\-\-type\fR is \fBgame\-loop\fR or \fBrobo\fR.

.TP 2m
\fB\-\-async\fR

Invoke a test asynchronously without waiting for test results.

.TP 2m
\fB\-\-client\-details\fR=[\fIKEY\fR=\fIVALUE\fR,...]

Comma\-separated, KEY=VALUE map of additional details to attach to the test
matrix. Arbitrary KEY=VALUE pairs may be attached to a test matrix to provide
additional context about the tests being run. When consuming the test results,
such as in Cloud Functions or a CI system, these details can add additional
context such as a link to the corresponding pull request.

Example:

.RS 2m
\-\-client\-details=buildNumber=1234,pullRequest=https://example.com/link/to/pull\-request
.RE

To help you identify and locate your test matrix in the Firebase console, use
the matrixLabel key.

Example:

.RS 2m
\-\-client\-details=matrixLabel="Example matrix label"
.RE

.TP 2m
\fB\-\-directories\-to\-pull\fR=[\fIDIR_TO_PULL\fR,...]

A list of paths that will be copied from the device's storage to the designated
results bucket after the test is complete. These must be absolute paths under
\f5/private/var/mobile/Media\fR or \f5/Documents\fR of the app under test. If
the path is under an app's \f5/Documents\fR, it must be prefixed with the app's
bundle id and a colon.

Example:

.RS 2m
\-\-directories\-to\-pull=com.my.app:/Documents/output,/private/var/mobile/Media/output
.RE

.TP 2m
\fB\-\-num\-flaky\-test\-attempts\fR=\fIint\fR

Specifies the number of times a test execution should be reattempted if one or
more of its test cases fail for any reason. An execution that initially fails
but succeeds on any reattempt is reported as FLAKY.

The maximum number of reruns allowed is 10. (Default: 0, which implies no
reruns.) All additional attempts are executed in parallel.

.TP 2m
\fB\-\-other\-files\fR=\fIDEVICE_PATH\fR=\fIFILE_PATH\fR,[...]

A list of device\-path=file\-path pairs that specify the paths of the test
device and the files you want pushed to the device prior to testing.

Device paths should either be under the Media shared folder (e.g. prefixed with
/private/var/mobile/Media) or within the documents directory of the filesystem
of an app under test (e.g. /Documents). Device paths to app filesystems should
be prefixed by the bundle ID and a colon. Source file paths may be in the local
filesystem or in Google Cloud Storage (gs://...).

Examples:

.RS 2m
\-\-other\-files com.my.app:/Documents/file.txt=local/file.txt,/private/var/mobile/Media/file.jpg=gs://bucket/file.jpg
.RE

.TP 2m
\fB\-\-record\-video\fR

Enable video recording during the test. Enabled by default, use
\-\-no\-record\-video to disable.

.TP 2m
\fB\-\-results\-bucket\fR=\fIRESULTS_BUCKET\fR

The name of a Google Cloud Storage bucket where raw test results will be stored
(default: "test\-lab\-<random\-UUID>"). Note that the bucket must be owned by a
billing\-enabled project, and that using a non\-default bucket will result in
billing charges for the storage used.

.TP 2m
\fB\-\-results\-dir\fR=\fIRESULTS_DIR\fR

The name of a \fBunique\fR Google Cloud Storage object within the results bucket
where raw test results will be stored (default: a timestamp with a random
suffix). Caution: if specified, this argument \fBmust be unique\fR for each test
matrix you create, otherwise results from multiple test matrices will be
overwritten or intermingled.

.TP 2m
\fB\-\-results\-history\-name\fR=\fIRESULTS_HISTORY_NAME\fR

The history name for your test results (an arbitrary string label; default: the
bundle ID for the iOS application). All tests which use the same history name
will have their results grouped together in the Firebase console in a
time\-ordered test history list.

.TP 2m
\fB\-\-robo\-script\fR=\fIROBO_SCRIPT\fR

The path to a Robo Script JSON file. The path may be in the local filesystem or
in Google Cloud Storage using gs:// notation. You can guide the Robo test to
perform specific actions by specifying a Robo Script with this argument. Learn
more at https://firebase.google.com/docs/test\-lab/robo\-ux\-test#scripting.
This flag is only valid when \fB\-\-type=robo\fR is also set.

.TP 2m
\fB\-\-scenario\-numbers\fR=\fIint\fR,[\fIint\fR,...]

A list of game\-loop scenario numbers which will be run as part of the test
(default: scenario 1). A maximum of 1024 scenarios may be specified in one test
matrix, but the maximum number may also be limited by the overall test
\fB\-\-timeout\fR setting. This flag is only valid when
\fB\-\-type=game\-loop\fR is also set.

.TP 2m
\fB\-\-test\-special\-entitlements\fR

Enables testing special app entitlements. Re\-signs an app having special
entitlements with a new application\-identifier. This currently supports testing
Push Notifications (aps\-environment) entitlement for up to one app in a
project.

Note: Because this changes the app's identifier, make sure none of the resources
in your zip file contain direct references to the test app's bundle id.


.RE
.sp

.SH "LIST COMMAND FLAGS"

.RS 2m
.TP 2m
\fB\-\-filter\fR=\fIEXPRESSION\fR

Apply a Boolean filter \fIEXPRESSION\fR to each resource item to be listed. If
the expression evaluates \f5True\fR, then that item is listed. For more details
and examples of filter expressions, run $ gcloud topic filters. This flag
interacts with other flags that are applied in this order: \fB\-\-flatten\fR,
\fB\-\-sort\-by\fR, \fB\-\-filter\fR, \fB\-\-limit\fR.

.TP 2m
\fB\-\-limit\fR=\fILIMIT\fR

Maximum number of resources to list. The default is \fBunlimited\fR. This flag
interacts with other flags that are applied in this order: \fB\-\-flatten\fR,
\fB\-\-sort\-by\fR, \fB\-\-filter\fR, \fB\-\-limit\fR.

.TP 2m
\fB\-\-page\-size\fR=\fIPAGE_SIZE\fR

Some services group resource list output into pages. This flag specifies the
maximum number of resources per page. The default is determined by the service
if it supports paging, otherwise it is \fBunlimited\fR (no paging). Paging may
be applied before or after \fB\-\-filter\fR and \fB\-\-limit\fR depending on the
service.

.TP 2m
\fB\-\-sort\-by\fR=[\fIFIELD\fR,...]

Comma\-separated list of resource field key names to sort by. The default order
is ascending. Prefix a field with ``~'' for descending order on that field. This
flag interacts with other flags that are applied in this order:
\fB\-\-flatten\fR, \fB\-\-sort\-by\fR, \fB\-\-filter\fR, \fB\-\-limit\fR.


.RE
.sp

.SH "GCLOUD WIDE FLAGS"

These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.

Run \fB$ gcloud help\fR for details.



.SH "NOTES"

This command is currently in alpha and might change without notice. If this
command fails with API permission errors despite specifying the correct project,
you might be trying to access an API with an invitation\-only early access
allowlist. These variants are also available:

.RS 2m
$ gcloud firebase test ios run
.RE

.RS 2m
$ gcloud beta firebase test ios run
.RE