feat: Add new gcloud commands, API clients, and third-party libraries across various services.

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/__init__.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android' sub-group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+class Android(base.Group):
+  """Command group for Android application testing."""
+
+  detailed_help = {
+      'DESCRIPTION': """\
+          Explore physical and virtual Android models, Android OS versions, and
+          Android locales which are available as test targets. Also run tests
+          against your Android app on these devices, monitor your test progress,
+          and view detailed test results in the Firebase console.
+          """,
+
+      'EXAMPLES': """\
+          To see a list of available Android devices, their form factors, and
+          supported Android OS versions, run:
+
+            $ {command} models list
+
+          To view more detailed information about a specific Android model, run:
+
+            $ {command} models describe MODEL_ID
+
+          To view details about available Android OS versions, such as their
+          code names and release dates, run:
+
+            $ {command} versions list
+
+          To view information about a specific Android OS version, run:
+
+            $ {command} versions describe VERSION_ID
+
+          To view the list of available Android locales which can be used for
+          testing internationalized applications, run:
+
+            $ {command} locales list
+
+          To view information about a specific locale, run:
+
+            $ {command} locales describe LOCALE
+
+          To view all options available for running Android tests, run:
+
+            $ {command} run --help
+      """
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags common to this sub-group.
+
+    Args:
+      parser: An argparse parser used to add arguments that immediately follow
+          this group in the CLI. Positional arguments are allowed.
+    """

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/list_device_capacities.py

@@ -0,0 +1,86 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2023 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android list-device-capacities' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.api_lib.firebase.test.device_capacities import DEVICE_CAPACITY_TABLE_FORMAT
+from googlecloudsdk.api_lib.firebase.test.device_capacities import DeviceCapacities
+from googlecloudsdk.calliope import base
+
+DETAILED_HELP = {
+    'EXAMPLES':
+        """
+    To list all published capacity information for Android devices, run:
+
+      $ {command}
+
+    To list capacity only for the model named 'redfin', run:
+
+      $ {command} --filter=redfin
+
+    To list capacities only for models that support API version 30, run:
+
+      $ {command} --filter=30
+    """,
+}
+
+
+class ListDeviceCapacities(base.ListCommand, DeviceCapacities):
+  """List capacity information for Android models & versions.
+
+    List device capacity information (high/medium/low/none) for all Android
+    models & versions which are available for testing and have capacity
+    information published.
+
+    Device capacity is the number of online devices in Firebase Test Lab. For
+    physical devices, the number is the average of online devices in the last 30
+    days. It's important to note that device capacity does not directly reflect
+    any real-time data, like the length of the test queue, or the
+    available/busy state of the devices based on current test traffic.
+  """
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    parser.display_info.AddFormat(DEVICE_CAPACITY_TABLE_FORMAT)
+    base.URI_FLAG.RemoveFromParser(parser)
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android list-device-capacities' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The list of device models, versions, and capacity info we want to have
+      printed later. Obsolete (unsupported) devices, versions, and entries
+      missing capacity info are filtered out.
+    """
+
+    return self.get_capacity_data(util.GetAndroidCatalog(self.context))
+
+
+ListDeviceCapacities.detailed_help = DETAILED_HELP

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/locales/__init__.py

@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android locales' command group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+class Locales(base.Group):
+  """Explore Android locales available for testing."""
+
+  detailed_help = {
+      'EXAMPLES': """\
+          To list all available Android locales which can be used for testing
+          international applications, run:
+
+            $ {command} list
+
+          To view information about a specific locale, run:
+
+            $ {command} describe LOCALE
+          """,
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags common to this sub-group.
+
+    Args:
+      parser: An argparse parser used to add arguments that immediately follow
+          this group in the CLI. Positional arguments are allowed.
+    """

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/locales/describe.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android locales describe' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import exceptions
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.calliope import base
+
+
+DETAILED_HELP = {
+    'EXAMPLES': """
+    To see the attributes of the Android locale 'my-locale', run:
+
+      $ {command} my-locale
+    """,
+}
+
+
+class Describe(base.DescribeCommand):
+  """Describe an Android locale."""
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    # Positional arg
+    parser.add_argument(
+        'locale',
+        help='The locale to describe, found using $ {parent_command} list.')
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android locales describe' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The testing_v1_messages.Locale object to describe.
+    """
+    catalog = util.GetAndroidCatalog(self.context)
+    for locale in catalog.runtimeConfiguration.locales:
+      if locale.id == args.locale:
+        return locale
+    raise exceptions.LocaleNotFoundError(args.locale)
+
+
+Describe.detailed_help = DETAILED_HELP

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/locales/list.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android locales list' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.calliope import base
+
+
+class List(base.ListCommand):
+  """List all Android locales available for testing internationalized apps."""
+
+  detailed_help = {
+      'EXAMPLES': """
+          To list all available locales which can be used for testing
+          internationalized Android applications, run:
+
+            $ {command}
+
+          To filter the locales to see only Spanish-speaking regions, run:
+
+            $ {command} --filter=Spanish
+          """,
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    parser.display_info.AddFormat("""
+          table[box](
+            id:label=LOCALE,
+            name,
+            region,
+            tags.list().color(green=default,red=deprecated,yellow=preview)
+          )
+    """)
+    base.URI_FLAG.RemoveFromParser(parser)
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android locales list' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The list of Android locales we want to have printed later.
+    """
+    catalog = util.GetAndroidCatalog(self.context)
+    return catalog.runtimeConfiguration.locales

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/models/__init__.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android models' command group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+class Models(base.Group):
+  """Explore Android models available in the Test Environment catalog."""
+
+  detailed_help = {
+      'EXAMPLES': """\
+          To list all Android models available for running tests, along with
+          their basic characteristics and supported Android OS versions, run:
+
+            $ {command} list
+
+          To view more detailed information about a specific Android model, run:
+
+            $ {command} describe MODEL_ID
+          """,
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags common to this sub-group.
+
+    Args:
+      parser: An argparse parser used to add arguments that immediately follow
+          this group in the CLI. Positional arguments are allowed.
+    """
+    pass

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/models/describe.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android models describe' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import exceptions
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.calliope import base
+
+DETAILED_HELP = {
+    'EXAMPLES': """
+      To see the attributes of the android model 'my-model', run:
+
+        $ {command} my-model
+    """,
+}
+
+
+class Describe(base.DescribeCommand):
+  """Describe an Android model."""
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    # Positional arg
+    parser.add_argument(
+        'model_id',
+        help='ID of the model to describe, found using '
+        '$ {parent_command} list.')
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android models describe' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The Android model we want to show a description of.
+    """
+    catalog = util.GetAndroidCatalog(self.context)
+    for model in catalog.models:
+      if model.id == args.model_id:
+        return model
+    raise exceptions.ModelNotFoundError(args.model_id)
+
+
+Describe.detailed_help = DETAILED_HELP

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/models/list.py

@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android models list' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.calliope import base
+from googlecloudsdk.core import log
+
+
+DETAILED_HELP = {
+    'EXAMPLES': """
+    To list all models which are available for testing, run:
+
+      $ {command}
+
+    To list all models made by Samsung, run:
+
+      $ {command} --filter=Samsung
+
+    To list all virtual device models, run:
+
+      $ {command} --filter=virtual
+    """,
+}
+
+
+class List(base.ListCommand):
+  """List all Android models available for testing."""
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    parser.display_info.AddFormat("""
+        table[box](
+          id:label=MODEL_ID,
+          manufacturer:label=MAKE,
+          name:label=MODEL_NAME,
+          form.color(blue=VIRTUAL,yellow=PHYSICAL,green=EMULATOR):label=FORM,
+          format("{0:4} x {1}", screenY, screenX):label=RESOLUTION,
+          supportedVersionIds.list(undefined="none"):label=OS_VERSION_IDS,
+          tags.join(sep=", ").color(green=default,red=deprecated,yellow=preview)
+        )
+    """)
+    base.URI_FLAG.RemoveFromParser(parser)
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android models list' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The list of device models we want to have printed later. Obsolete models
+      with no currently supported OS versions are filtered out.
+    """
+    catalog = util.GetAndroidCatalog(self.context)
+    filtered_models = [
+        model for model in catalog.models if model.supportedVersionIds
+    ]
+    self._epilog = util.GetDeprecatedTagWarning(filtered_models, 'android')
+
+    return filtered_models
+
+  def Epilog(self, resources_were_displayed=True):
+    super(List, self).Epilog(resources_were_displayed)
+
+    if self._epilog:
+      log.warning(self._epilog)
+
+
+List.detailed_help = DETAILED_HELP

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/run.py

@@ -0,0 +1,311 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""The 'gcloud firebase test android run' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import arg_util
+from googlecloudsdk.api_lib.firebase.test import ctrl_c_handler
+from googlecloudsdk.api_lib.firebase.test import exit_code
+from googlecloudsdk.api_lib.firebase.test import history_picker
+from googlecloudsdk.api_lib.firebase.test import matrix_ops
+from googlecloudsdk.api_lib.firebase.test import results_bucket
+from googlecloudsdk.api_lib.firebase.test import results_summary
+from googlecloudsdk.api_lib.firebase.test import tool_results
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.api_lib.firebase.test.android import arg_manager
+from googlecloudsdk.api_lib.firebase.test.android import matrix_creator
+from googlecloudsdk.calliope import base
+from googlecloudsdk.core import log
+import six
+
+_APK_MIME_TYPE = 'application/vnd.android.package-archive'
+
+
+@base.UnicodeIsSupported
+class _BaseRun(object):
+  """Invoke a test in Firebase Test Lab for Android and view test results."""
+
+  detailed_help = {
+      'DESCRIPTION': """
+          *{command}* invokes and monitors tests in Firebase Test Lab for
+          Android.
+
+          Three main types of Android tests are currently supported:
+          - *robo*: runs a smart, automated exploration of the activities in
+            your Android app which records any installation failures or crashes
+            and builds an activity map with associated screenshots and video.
+          - *instrumentation*: runs automated unit or integration tests written
+            using a testing framework. Firebase Test Lab for Android currently
+            supports the Espresso and UI Automator 2.0 testing
+            frameworks.
+          - *game-loop*: executes a special intent built into the game app (a
+            "demo mode") that simulates the actions of a real player. This test
+            type can include multiple game loops (also called "scenarios"),
+            which can be logically organized using scenario labels so that you
+            can run related loops together. Refer to
+            https://firebase.google.com/docs/test-lab/android/game-loop for
+            more information about how to build and run Game Loop tests.
+
+          The type of test to run can be specified with the *--type* flag,
+          although the type can often be inferred from other flags.
+          Specifically, if the *--test* flag is present, the test *--type*
+          defaults to `instrumentation`. If *--test* is not present, then
+          *--type* defaults to `robo`.
+
+          All arguments for *{command}* may be specified on the command line
+          and/or within an argument file. Run *$ gcloud topic arg-files* for
+          more information about argument files.
+          """,
+      'EXAMPLES': """
+          To invoke a robo test lasting 100 seconds against the default device
+          environment, run:
+
+            $ {command} --app=APP_APK --timeout=100s
+
+          When specifying devices to test against, the preferred method is to
+          use the --device flag. For example, to invoke a robo test against a
+          virtual, generic MDPI Nexus device in landscape orientation, run:
+
+            $ {command} --app=APP_APK --device=model=NexusLowRes,orientation=landscape
+
+          To invoke an instrumentation test against a physical Nexus 6 device
+          (MODEL_ID: shamu) which is running Android API level 21 in French, run:
+
+            $ {command} --app=APP_APK --test=TEST_APK --device=model=shamu,version=21,locale=fr
+
+          To test against multiple devices, specify --device more than once:
+
+            $ {command} --app=APP_APK --test=TEST_APK --device=model=Nexus4,version=19 --device=model=Nexus4,version=21 --device=model=NexusLowRes,version=25
+
+          To invoke a robo test on an Android App Bundle, pass the .aab file
+          using the --app flag.
+
+            $ {command} --app=bundle.aab
+
+          You may also use the legacy dimension flags (deprecated) to specify
+          which devices to use. Firebase Test Lab will run tests against every
+          possible combination of the listed device dimensions. Note that some
+          combinations of device models and OS versions may not be valid or
+          available in Test Lab. Any unsupported combinations of dimensions in
+          the test matrix will be skipped.
+
+          For example, to execute a series of 5-minute robo tests against a very
+          comprehensive matrix of virtual and physical devices, OS versions,
+          locales and orientations, run:
+
+            $ {command} --app=APP_APK --timeout=5m --device-ids=shamu,NexusLowRes,Nexus5,g3,zeroflte --os-version-ids=19,21,22,23,24,25 --locales=en_GB,es,fr,ru,zh --orientations=portrait,landscape
+
+          The above command will generate a test matrix with a total of 300 test
+          executions, but only the subset of executions with valid dimension
+          combinations will actually run your tests.
+
+          To help you identify and locate your test matrix in the Firebase
+          console, run:
+
+            $ {command} --app=APP_APK --client-details=matrixLabel="Example matrix label"
+
+          Controlling Results Storage
+
+          By default, Firebase Test Lab stores detailed test results for a
+          limited time in a Google Cloud Storage bucket provided for you at
+          no charge. Note: This requires the principal executing the test to
+          have "roles/editor" role for the project. If either you do not have
+          that role, you wish to use a storage bucket that you control, or you
+          need to retain detailed test results for a longer period, use the
+          *--results-bucket* option. See
+          https://firebase.google.com/docs/test-lab/analyzing-results#detailed
+          for more information.
+
+          Detailed test result files are prefixed by default with a timestamp
+          and a random character string. If you require a predictable path
+          where detailed test results are stored within the results bucket
+          (say, if you have a Continuous Integration system which does custom
+          post-processing of test result artifacts), use the *--results-dir*
+          option. _Note that each test invocation *must* have a unique storage
+          location, so never reuse the same value for *--results-dir* between
+          different test runs_. Possible strategies could include using a UUID
+          or sequence number for *--results-dir*.
+
+          For example, to run a robo test using a specific Google Cloud Storage
+          location to hold the raw test results, run:
+
+            $ {command} --app=APP_APK --results-bucket=gs://my-bucket --results-dir=my/test/results/<unique-value>
+
+          To run an instrumentation test and specify a custom name under which
+          the history of your tests will be collected and displayed in the
+          Firebase console, run:
+
+            $ {command} --app=APP_APK --test=TEST_APK --results-history-name='Excelsior App Test History'
+
+          Argument Files
+
+          All test arguments for a given test may alternatively be stored in an
+          argument group within a YAML-formatted argument file. The _ARG_FILE_
+          may contain one or more named argument groups, and argument groups may
+          be combined using the `include:` attribute (Run *$ gcloud topic
+          arg-files* 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
+          *excelsior_args*, which contains an argument group named *robo-args:*,
+          use the following syntax:
+
+            $ {command} path/to/excelsior_args:robo-args
+          """,
+  }
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test run' command to invoke a test in Test Lab.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      One of:
+        - a list of TestOutcome tuples (if ToolResults are available).
+        - a URL string pointing to the user's results in ToolResults or GCS.
+    """
+    if args.async_ and not args.IsSpecified('format'):
+      args.format = """
+          value(format(
+            'Final test results will be available at [ {0} ].', [])
+          )
+      """
+    log.status.Print('\nHave questions, feedback, or issues? Get support by '
+                     'visiting:\n  https://firebase.google.com/support/\n')
+
+    arg_manager.AndroidArgsManager().Prepare(args)
+
+    project = util.GetProject()
+    tr_client = self.context['toolresults_client']
+    tr_messages = self.context['toolresults_messages']
+    storage_client = self.context['storage_client']
+
+    bucket_ops = results_bucket.ResultsBucketOps(project, args.results_bucket,
+                                                 args.results_dir, tr_client,
+                                                 tr_messages, storage_client)
+    bucket_ops.UploadFileToGcs(args.app, _APK_MIME_TYPE)
+    if args.test:
+      bucket_ops.UploadFileToGcs(args.test, _APK_MIME_TYPE)
+    for obb_file in (args.obb_files or []):
+      bucket_ops.UploadFileToGcs(obb_file, 'application/octet-stream')
+    if getattr(args, 'robo_script', None):
+      bucket_ops.UploadFileToGcs(args.robo_script, 'application/json')
+    additional_apks = getattr(args, 'additional_apks', None) or []
+    for additional_apk in additional_apks:
+      bucket_ops.UploadFileToGcs(additional_apk, _APK_MIME_TYPE)
+    other_files = getattr(args, 'other_files', None) or {}
+    for device_path, file_to_upload in six.iteritems(other_files):
+      bucket_ops.UploadFileToGcs(
+          file_to_upload,
+          None,
+          destination_object=util.GetRelativeDevicePath(device_path))
+    bucket_ops.LogGcsResultsUrl()
+
+    tr_history_picker = history_picker.ToolResultsHistoryPicker(
+        project, tr_client, tr_messages)
+    history_name = PickHistoryName(args)
+    history_id = tr_history_picker.GetToolResultsHistoryId(history_name)
+
+    matrix = matrix_creator.CreateMatrix(args, self.context, history_id,
+                                         bucket_ops.gcs_results_root,
+                                         six.text_type(self.ReleaseTrack()))
+    monitor = matrix_ops.MatrixMonitor(matrix.testMatrixId, args.type,
+                                       self.context)
+
+    with ctrl_c_handler.CancellableTestSection(monitor):
+      tr_ids = tool_results.GetToolResultsIds(matrix, monitor)
+      matrix = monitor.GetTestMatrixStatus()
+      supported_executions = monitor.HandleUnsupportedExecutions(matrix)
+
+      url = tool_results.CreateToolResultsUiUrl(project, tr_ids)
+      log.status.Print('')
+      if args.async_:
+        return url
+      log.status.Print('Test results will be streamed to [ {0} ].'.format(url))
+
+      # If we have exactly one testExecution, show detailed progress info.
+      if len(supported_executions) == 1 and args.num_flaky_test_attempts == 0:
+        monitor.MonitorTestExecutionProgress(supported_executions[0].id)
+      else:
+        monitor.MonitorTestMatrixProgress()
+
+    log.status.Print('\nMore details are available at [ {0} ].'.format(url))
+    # Fetch the per-dimension test outcomes list, and also the "rolled-up"
+    # matrix outcome from the Tool Results service.
+    summary_fetcher = results_summary.ToolResultsSummaryFetcher(
+        project, tr_client, tr_messages, tr_ids, matrix.testMatrixId)
+    self.exit_code = exit_code.ExitCodeFromRollupOutcome(
+        summary_fetcher.FetchMatrixRollupOutcome(),
+        tr_messages.Outcome.SummaryValueValuesEnum)
+    return summary_fetcher.CreateMatrixOutcomeSummaryUsingEnvironments()
+
+
+@base.ReleaseTracks(base.ReleaseTrack.GA)
+class RunGA(_BaseRun, base.ListCommand):
+  """Invoke a test in Firebase Test Lab for Android and view test results."""
+
+  @staticmethod
+  def Args(parser):
+    arg_util.AddCommonTestRunArgs(parser)
+    arg_util.AddMatrixArgs(parser)
+    arg_util.AddAndroidTestArgs(parser)
+    arg_util.AddGaArgs(parser)
+    base.URI_FLAG.RemoveFromParser(parser)
+    parser.display_info.AddFormat(util.OUTCOMES_FORMAT)
+
+
+@base.ReleaseTracks(base.ReleaseTrack.ALPHA, base.ReleaseTrack.BETA)
+class RunBeta(_BaseRun, base.ListCommand):
+  """Invoke a test in Firebase Test Lab for Android and view test results."""
+
+  @staticmethod
+  def Args(parser):
+    arg_util.AddCommonTestRunArgs(parser)
+    arg_util.AddMatrixArgs(parser)
+    arg_util.AddAndroidTestArgs(parser)
+    arg_util.AddAndroidBetaArgs(parser)
+    arg_util.AddBetaArgs(parser)
+    base.URI_FLAG.RemoveFromParser(parser)
+    parser.display_info.AddFormat(util.OUTCOMES_FORMAT)
+
+
+def PickHistoryName(args):
+  """Returns the results history name to use to look up a history ID.
+
+  The history ID corresponds to a history name. If the user provides their
+  own history name, we use that to look up the history ID; If not, but the user
+  provides an app-package name, we use the app-package name with ' (gcloud)'
+  appended as the history name. Otherwise, we punt and let the Testing service
+  determine the appropriate history ID to publish to.
+
+  Args:
+    args: an argparse namespace. All the arguments that were provided to the
+      command invocation (i.e. group and command arguments combined).
+
+  Returns:
+    Either a string containing a history name derived from user-supplied data,
+    or None if we lack the required information.
+  """
+  if args.results_history_name:
+    return args.results_history_name
+  if args.app_package:
+    return args.app_package + ' (gcloud)'
+  return None

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/versions/__init__.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android versions' command group."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.calliope import base
+
+
+class Versions(base.Group):
+  """Explore Android versions available for testing."""
+
+  detailed_help = {
+      'EXAMPLES': """\
+          To list information about all versions of the Android OS available
+          for running tests, including details such as OS code name and
+          release date, run:
+
+            $ {command} list
+
+          To view information about a specific Android OS version, run:
+
+            $ {command} describe VERSION_ID
+          """,
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags common to this sub-group.
+
+    Args:
+      parser: An argparse parser used to add arguments that immediately follow
+          this group in the CLI. Positional arguments are allowed.
+    """

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/versions/describe.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android versions describe' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import exceptions
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.calliope import base
+
+
+DETAILED_HELP = {
+    'EXAMPLES': """
+    To see attributes of the Android OS version 'my-version', run:
+
+      $ {command} my-version
+    """,
+}
+
+
+class Describe(base.DescribeCommand):
+  """Describe an Android OS version."""
+
+  detailed_help = {
+      'DESCRIPTION': 'Describe an Android OS version.',
+      'EXAMPLES': """To describe an Android OS version available for testing,
+run:
+
+  {command} Q
+
+To describe an Android OS version available for testing in JSON format,
+run:
+
+  {command} Q --format=json
+"""
+  }
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    # Positional arg
+    parser.add_argument(
+        'version_id',
+        help='The version ID to describe, found using $ {parent_command} list.')
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android versions describe' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The testing_v1_messages.AndroidVersion object to describe.
+    """
+    catalog = util.GetAndroidCatalog(self.context)
+    for version in catalog.versions:
+      if version.id == args.version_id:
+        return version
+    raise exceptions.VersionNotFoundError(args.version_id)
+
+
+Describe.detailed_help = DETAILED_HELP

gcloud auth application-default login/google-cloud-sdk/lib/surface/firebase/test/android/versions/list.py

@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*- #
+# Copyright 2017 Google LLC. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""The 'gcloud firebase test android versions list' command."""
+
+from __future__ import absolute_import
+from __future__ import division
+from __future__ import unicode_literals
+
+from googlecloudsdk.api_lib.firebase.test import util
+from googlecloudsdk.calliope import base
+
+DETAILED_HELP = {
+    'EXAMPLES': """
+      To list all versions available for testing, run:
+
+        $ {command}
+    """,
+}
+
+
+class List(base.ListCommand):
+  """List all Android OS versions available for testing."""
+
+  @staticmethod
+  def Args(parser):
+    """Method called by Calliope to register flags for this command.
+
+    Args:
+      parser: An argparse parser used to add arguments that follow this
+          command in the CLI. Positional arguments are allowed.
+    """
+    parser.display_info.AddFormat("""
+          table[box](
+            id:label=OS_VERSION_ID:align=center,
+            versionString:label=VERSION:align=center,
+            codeName,
+            apiLevel:align=center,
+            releaseDate.date(format='%Y-%m-%d'):align=center,
+            tags.list().color(green=default,red=deprecated,yellow=preview)
+          )
+    """)
+    base.URI_FLAG.RemoveFromParser(parser)
+
+  def Run(self, args):
+    """Run the 'gcloud firebase test android versions list' command.
+
+    Args:
+      args: an argparse namespace. All the arguments that were provided to this
+        command invocation (i.e. group and command arguments combined).
+
+    Returns:
+      The list of Android OS versions we want to have printed later.
+    """
+    catalog = util.GetAndroidCatalog(self.context)
+    return catalog.versions
+
+
+List.detailed_help = DETAILED_HELP