.TH "GCLOUD_FIREBASE_TEST_IOS_RUN" 1



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



.SH "SYNOPSIS"
.HP
\f5gcloud 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\-\-app\fR=\fIAPP\fR] [\fB\-\-async\fR] [\fB\-\-client\-details\fR=[\fIKEY\fR=\fIVALUE\fR,...]] [\fB\-\-num\-flaky\-test\-attempts\fR=\fIint\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\-\-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"

\fBgcloud firebase test ios run\fR invokes and monitors tests in Firebase Test
Lab for iOS.

The currently supported iOS test frameworks are XCTest and XCUITest. 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.

All arguments for \fBgcloud 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 invoke an XCTest lasting up to five minutes against the default device
environment, run:

.RS 2m
$ gcloud 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 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 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 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 firebase test ios run \-\-test=XCTEST_ZIP \e
    \-\-client\-details=matrixLabel="Example matrix label"
.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 firebase test ios run 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 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
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\-\-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\-\-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\-\-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\-\-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"

These variants are also available:

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

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