Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

本指南介绍如何使用 gcloud beta device-run CLI 运行 Android 插桩测试或独立的 Android 可执行文件，以及如何在 Google Cloud 控制台中查找结果。本指南假定您拥有 Google Cloud 账号和项目。

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

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

准备工作

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

创建 Google Cloud 项目。
按照快速入门设置 Developer Device Platform。
在终端中通过 gcloud 进行身份验证。
查看Device Run 概览，了解一般信息。
为 Android 构建插桩测试，或准备独立的 Android 可执行文件（例如编译后的 C++ 二进制文件、基准测试运行程序或 Shell 脚本）。

第 1 步：配置测试或可执行文件的运行

现在，您已运行会话，接下来可以探索一些配置选项：

插桩测试和可执行文件的选项

多个设备：如需在多个设备上运行同一测试或可执行文件，请提供 --device 标志，并使用英文逗号分隔多个设备 ID（例如 --device shiba-34,tokay-36），或提供多个 --device 标志，每个标志指定一个不同的设备 ID（例如 --device shiba-34 --device tokay-36）。
将文件推送到设备：使用 --other-files-to-push=SOURCE=DEST,...在执行前将其他文件（例如 ML 模型权重、测试输入或 .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,...将用户定义的键值对标签附加到会话。

插桩测试选项

其他应用：您可以选择指定一个或多个 APK、AAB 或 APKS 文件，以便在运行测试之前使用 --apps=path1,path2,...,path_n 标志进行安装。您指定的顺序就是这些应用的安装顺序。
测试超时：限制执行时长： --instrumentation-timeout=10m（有效范围为1m到3h，默认为 5m）。

Android 可执行文件选项

可执行文件实参：使用 --executable-args=ARG,...以英文逗号分隔列表的形式或通过重复标志将命令行实参传递给可执行文件。每个元素都成为一个参数，因此请将以空格分隔的命令行重写为以逗号分隔的形式（例如 --executable-args="--input=a.file,--threads=4"）。如需传递本身包含逗号的参数，请在值前面加上^SEP^以指定不同的分隔符（例如 --executable-args="^;^--shape=1,224,224,3;--threads=4"）。
环境变量：使用 --executable-env-vars=KEY=VALUE,... 为设备上的可执行文件进程设置环境变量（例如 --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib）。
可执行文件超时：限制可执行文件的执行时长： --executable-timeout=10m（有效范围为 1m 到 3h，默认为 5m，不包括设备准备和清理时间）。

同步和异步运行

默认情况下，提交命令是阻塞（同步） 的。它将等待测试或可执行文件完成，并输出结果的摘要表。

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

Android 插桩测试

对于：

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

Android 可执行文件

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

这会立即返回会话 ID。然后，您可以使用 sessions wait 命令等待它：

gcloud beta device-run sessions wait SESSION_ID

该命令将阻塞，直到作业完成。

多个设备

如需在多个设备上运行同一测试或可执行文件，请提供 --device 标志，并使用英文逗号分隔多个设备 ID，或提供多个 --device 标志，每个标志指定一个不同的设备 ID。

Android 插桩测试

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

Android 可执行文件

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

或：

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

测试和可执行文件超时

限制测试或可执行文件的执行时长：

Android 插桩测试

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

Android 可执行文件

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

对于 Android 运行，有效范围为 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。

启用 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 版本。

第 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 可执行文件。

运行插桩测试

请注意，以下标志是 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

运行 Android 可执行文件

如需直接在 Android 设备上运行独立的可执行文件（例如编译后的 C++ 二进制文件、设备端机器学习基准测试运行程序（如 LiteRT）或 Shell 脚本），而无需将其打包到 APK 中，请使用 sessions submit android-executable 命令。

请注意，以下标志是 Android 可执行文件所必需的：

设备：使用 --device 指定设备：--device shiba-35
可执行文件：指定可执行文件的本地路径或 Cloud Storage 路径，--executable：--executable /path/to/my_executable

如需运行可执行文件，请发出类似于以下内容的命令，并使用您自己的设备 ID 和可执行文件路径：

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

作业的结果报告文件夹位于 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 会使用历史测试作业时间创建不同的分片，并尝试在相似的时长内完成所有分片。

统一分片

如需使用统一分片对测试进行分片，请在 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=（以分钟或 1 小时为单位）和 --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 - 指定智能分片中每个分片的目标执行时间（例如 2 分钟、10 分钟、1 小时）。有效范围为 2 分钟到 1 小时。当 --sharding-option=smart 时为必需。
--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - 指定智能分片记录文件的名称，不包括文件扩展名。当 --sharding-option=smart 时为必需。此 YAML 文件位于 Google Cloud --bucket-name下指定的存储桶中的 smart-sharding/ 目录下。如果该文件不存在，系统会自动创建；否则，其内容会在会话完成后更新。

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

对于 sessions submit instrumentation 和 sessions submit android-executable 命令的异步和同步模式，您都可以使用 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` 列表命令支持所有 ``标准 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） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

第 1 步：配置测试或可执行文件的运行

插桩测试和可执行文件的选项

插桩测试选项

Android 可执行文件选项

同步和异步运行

Android 插桩测试

Android 可执行文件

多个设备

Android 插桩测试

Android 可执行文件

测试和可执行文件超时

Android 插桩测试

Android 可执行文件

软件版本

启用 Orchestrator

第 2 步：选择设备

第 3 步：运行测试或可执行文件

运行插桩测试

运行 Android 可执行文件

第 4 步：使用分片

第 4.1 步：选择分片选项

统一分片

智能分片

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

后续步骤

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