开发者设备平台设备运行（适用于 Android）

预览

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

本指南介绍了如何使用 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 步：选择设备

使用 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）在提交命令中。

第 2 步：运行插桩测试

请注意，以下标志是 Android 测试所必需的：

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

如需运行测试，请发出类似于以下内容的命令，但要使用您自己的设备 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/。

第 3 步：配置测试运行

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

现在，您已经运行了测试，接下来可以探索一些配置选项：

• 多台设备：如需在多台设备上运行相同的测试，请提供 --device 标志，并以英文逗号分隔多个设备 ID，例如 --device shiba-34,tokay-36；或者提供多个 --device 标志，每个标志指定一个不同的设备 ID（例如 --device shiba-34 --device tokay-36）。
• 其他应用：您可以选择使用 --apps=path1,path2,...,path_n 标志指定一个或多个要在运行测试之前安装的 APK。您指定的顺序就是这些应用的安装顺序。
• 测试超时：限制执行时长：--instrumentation-timeout=10m（有效范围为 1m 到 1h，默认值为 5m）。
• 自定义 Cloud Storage 存储桶：如果您未使用 --bucket-name= 标志指定 Cloud Storage 存储桶，Google Cloud CLI 将使用名为 PROJECT_ID-devicerun 的默认存储桶。
• 不可靠的测试重试：设置重新运行不可靠的测试的尝试次数上限：--flaky-test-attempts=3（默认值为 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 标志相应地增加插桩超时设置。

第 4 步：使用分片

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

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

第 4.1 步。选择分片选项

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

开发者设备平台同时支持智能分片和统一分片。在决定如何对测试进行分片时，请考虑以下选项：

• 如果所有测试用例的耗时都差不多，请使用均匀分片，将所有测试用例分成 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

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

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 - 为智能分片指定每个分片的目标执行时间（例如 2 分钟、10 分钟、1 小时）。有效范围为 2 分钟到 1 小时。当 --sharding-option=smart 时为必需。

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

第 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

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

如果会话已结束，则仅打印当前状态。 请求取消已完成的会话不会出错。

后续步骤

接下来，我们将查找和分析日志。