适用于 Android 插桩测试的 Developer Device Platform Device Run

预览

此产品或功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

本指南介绍了如何使用 gcloud beta device-run CLI 运行 Android 插桩测试，以及如何在 Google Cloud 控制台中查找测试结果。它假定您拥有一个 Google Cloud 账号和项目。

如果您要从 Firebase Test Lab 迁移到 Developer Device Platform，请参阅我们的迁移指南、命令和标志转换以及 AI 智能体的迁移技能。

如需使用此 Google Cloud CLI，您需要提供 Google Cloud 项目 ID。如需查看命令摘要，请参阅 gcloud beta device-run。

准备工作

这些步骤假定您已完成以下操作：

1. 创建了 Google Cloud 项目。
2. 按照快速入门中的说明设置 Developer Device Platform。
3. 在终端中使用 gcloud 进行了身份验证。
4. 查看了 Device Run 概览，了解一般信息。
5. 构建了针对 Android 的插桩测试。

第 1 步：配置测试运行

提示： 如需查看 submit 命令的所有可用选项，请运行 gcloud beta device-run sessions submit instrumentation --help。

Android 插桩测试选项

• 多台设备：如需在多台设备上运行同一测试，请提供 --device 标志，后跟多个设备 ID（以英文逗号分隔，例如 --device shiba-34,tokay-36），或提供多个 --device 标志，每个标志指定一个不同的设备 ID（例如 --device shiba-34 --device tokay-36）。
• 将文件推送到设备：在执行之前，使用 --other-files-to-push=SOURCE=DEST,... 将其他文件（例如机器学习模型权重、测试输入或 .so 共享库）推送到设备。SOURCE 支持本地路径和 Cloud Storage (gs://...) 路径，DEST 是设备上的目标路径。
• 从设备拉取文件：执行完成后，使用 --paths-to-pull=DEVICE_PATH,... 从设备拉取生成的文件或目录。
• 自定义 Cloud Storage 存储桶：使用 --bucket-name= 指定现有 Cloud Storage 存储桶名称（不带 gs:// 架构或路径）。如果您未指定存储桶，Google Cloud CLI 会使用或创建名为 PROJECT_ID-devicerun 的默认存储桶。
• 不可靠的测试重试次数：设置每个作业或分片处理不可靠测试的最大尝试次数：--flaky-test-attempts=3（默认值为 1 次尝试）。
• 设备环境和诊断：配置设备屏幕方向（--orientation=portrait 或 landscape）、语言区域 (--locale=en-US)、模拟 GPS 位置 (--coordinates=LATITUDE,LONGITUDE)、屏幕录像（--video=always 或 on-failure）、dumpsys 收集（--dumpsys=always 或 on-failure）或 bugreport 收集（--bugreport=always 或 on-failure）。
• 标签：使用 --labels=KEY=VALUE,... 将用户定义的键值对标签附加到会话。
• 其他应用：您可以视情况使用 --apps=path1,path2,...,path_n 标志指定一个或多个要在运行测试之前安装的 APK、AAB 或 APKS 文件。您指定的顺序就是这些应用的安装顺序。
• 测试超时：限制执行时长：--instrumentation-timeout=10m（有效范围为 1m 到 3h，默认值为 5m）。

同步和异步运行

默认情况下，提交命令是阻塞（同步）的。它会等待测试完成，然后输出结果摘要表。

如需在将文件上传到 Cloud Storage 后立即提交会话并返回，请添加 --async 标志：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

此操作会立即返回会话 ID。然后，您可以使用 sessions wait 命令等待其完成：

gcloud beta device-run sessions wait SESSION_ID

该命令会一直处于阻塞状态，直到作业完成。

多个设备

如需在多台设备上运行同一测试，请提供 --device 标志以及多个设备 ID（以英文逗号分隔），或提供多个 --device 标志（每个标志指定一个不同的设备 ID）：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

或：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

测试超时

限制测试的执行时长：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

有效范围为 1m 到 3h，默认值为 5m。

软件版本

在配置测试运行之前，发现并使用 AndroidX Test Orchestrator 的可用软件包和版本，并检查其生命周期、支持的版本和元数据。

首先，列出所有可用的软件包及其版本：

gcloud beta device-run software-versions list

您会收到类似以下内容的输出：

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

然后，使用列表中的确切资源 ID 描述特定软件包：

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

您会收到类似以下内容的输出：

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

现在，您已经知道有哪些软件版本可用，接下来就可以在测试运行中使用 --orchestrator-version 标志来使用这些版本，如下所示：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

启用 Orchestrator

Developer Device Platform 支持 Android Test Orchestrator，可让您在测试自己的 Instrumentation 调用中运行每一项应用测试。

使用 Orchestrator 时，您：

• 避免共享状态。每个测试都在自己的 Instrumentation 实例中运行。因此，如果您的测试共享应用状态，则在每次测试后，大部分共享状态都会从设备的 CPU 或内存中移除。如需在每次测试后从设备的 CPU 和内存中移除所有共享状态，请添加 clearPackageData 设置，如下所示：--additional-test-options clearPackageData=true

• 隔离崩溃。即使有一个测试崩溃了，也只会破坏它自己的 Instrumentation 实例。这意味着您的其他测试仍会运行并提供完整的测试结果。

在 Developer Device Platform 中，Android Test Orchestrator 默认处于关闭状态。如需同时启用 Orchestrator 并指定要在测试作业期间使用的版本，请将您选择的版本传递给 sessions submit instrumentation 命令中的 --orchestrator-version=ORCHESTRATOR_VERSION 标志，如下所示：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

将该标志设置为 auto，以使用系统默认的 Orchestrator 版本。

注意： 由于每个 Orchestrator 测试都会运行自己的 Instrumentation 实例，因此增加的运行时间可能会增加您的配额用量或计费时间，并导致您超出设备的超时限制。您可能需要使用 --instrumentation-timeout 标志相应地增加插桩超时设置。

第 2 步：选择设备

使用 device-run CLI，可以在可用的实体设备和虚拟设备上运行 Android 测试。如需查看可用设备的完整列表，请访问交互式设备目录或运行以下命令：

gcloud beta device-run devices list

输出示例：

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

请参阅设备目录，了解如何过滤此列表。如需在执行时定位到特定设备，请在提交命令中使用其对应的 ID（例如 tegu-35）。

第 3 步：运行测试

提交 Android 插桩测试 APK。

Android 插桩测试需要以下标志：

• 设备：使用 --device 指定设备：--device shiba-35
• 测试：使用 --test 指定测试 APK：--test /path/to/test.apk

如需运行插桩测试，请发出类似于以下内容的 sessions submit instrumentation 命令，并使用您自己的设备 ID 和测试路径：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

您可以在 Cloud Storage 路径（例如 gs://BUCKET_NAME/automation/sessions/SESSION_ID/）中找到作业的结果报告文件夹。请参阅命令输出中的链接，如下所示：https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/。

第 4 步：使用分片

如需在持续集成和持续交付 (CI/CD) 工作流中添加 Developer Device Platform 插桩测试，您应考虑对测试进行分片。测试分片旨在将一组插桩测试划分为多个独立运行的子组（分片）。Developer Device Platform 会自动使用多个设备并发运行各个分片，从而在更短的时间内完成整个测试集。

注意： 分片测试的费用可能会较高。虽然测试分片会缩短运行所有测试所花费的时间，但在每个分片上启动您的应用所产生的开销可能会增加各个设备的时间。

第 4.1 步：选择分片选项

如果您的作业只有少量测试用例，或者所有测试用例的总执行时间不长，则无需使用分片。如果您有大量测试用例，或者所有测试用例的总执行时间较长，请考虑使用分片。

Developer Device Platform 支持智能分片和统一分片。在决定如何对测试进行分片时，请考虑以下选项：

• 如果所有测试用例所需的时间大致相同，请使用统一分片，将所有测试用例分成 n 个分片。

• 当不同测试用例的执行时间差异很大时，请使用智能分片。Developer Device Platform 会使用历史测试作业执行时间来创建不同的分片，并尝试在相似的时长内完成所有分片。

注意： 分片数量是可配置的，因此当 Developer Device Platform 并行运行多个分片时，测试运行可能会因设备可用性而遇到瓶颈。因此，我们建议在 --device 标志中指定的设备数量小于或等于分片数量。

均匀分片

如需使用统一分片对测试进行分片，请在 sessions submit instrumentation 命令中添加 --sharding-option=uniform 和 --uniform-sharding-count= 标志，如下所示：

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

您应该会看到指示 Job status: 2 running 的输出。该服务会创建两个作业，每个设备一个。由于两个作业的输入相同，因此服务会集中进行验证，仅执行一次。

完成后，您会在命令的最终输出中看到这两个作业分别列出：

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

智能分片

如需使用智能分片对测试进行分片，请在 sessions submit instrumentation 命令中添加 --sharding-option=smart、--smart-sharding-max-shard-count=、--smart-sharding-target-duration=（以分钟或 1h 为单位）和 --smart-sharding-record-name= 标志，如下所示：

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

您应该会看到最终输出，其中显示运行了三个作业：

Session [session-3cd0564a] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED
job-002   execution-000   PASSED

下面简要介绍了此处使用的智能分片标志：

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - 指定要为智能分片创建的分片数上限。如果未设置或设置为 0，则系统会使用系统定义的最大限制。实体设备的有效范围为 0 到 20，虚拟设备的有效范围为 0 到 200。

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - 为智能分片指定每个分片的目标执行时间（例如 2m、10m、1h）。有效范围为 2 分钟到 1 小时。如果 --sharding-option=smart，则为必需。

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - 指定智能分片记录文件的名称（不含文件扩展名）。当 --sharding-option=smart 时，此参数为必需。此 YAML 文件位于 smart-sharding/ 目录下由 --bucket-name 指定的 Google Cloud存储桶中。如果该文件不存在，系统会自动创建；否则，系统会在会话完成后更新其内容。

第 5 步：探索和管理测试运行

对于 sessions submit instrumentation 命令的异步和同步模式，您可以使用 sessions describe 命令在执行期间查询作业状态，或在作业完成后获取结果：

gcloud beta device-run sessions describe SESSION_ID

输出会汇总测试结果，并提供指向 Google Cloud 控制台中结果的链接。 例如：

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

使用以下命令列出所有正在运行和已完成的会话：

gcloud beta device-run sessions list

您将收到包含项目中会话列表的输出，如下所示：

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

sessions list 命令支持所有标准 Google Cloud CLI 标志选项。例如：

gcloud beta device-run sessions list --limit 5

这会产生类似于以下内容的结果：

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

或者，如需查找所有正在运行的会话，请运行：

gcloud beta device-run sessions list --filter RUNNING

假设您有正在运行的会话，您会看到类似以下内容的结果：

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

否则，您将收到 Listed 0 items.

如需取消正在运行的会话，请使用您的会话 ID 运行以下命令：

gcloud beta device-run sessions cancel SESSION_ID

该命令会立即返回，因为会话仅标记为取消。取消操作会在后端异步进行。

如果会话已完成，则仅输出当前状态。 请求取消已完成的会话不会导致错误。

后续步骤

接下来，运行 Android 可执行文件或查找并分析日志。