本指南介绍了如何使用 gcloud beta device-run CLI 运行 Android 插桩测试，以及如何在 Google Cloud 控制台中查找结果。本教程假设您拥有 Google Cloud 账号和项目。
如需使用此 Google Cloud CLI，您需要提供 Google Cloud 项目 ID。如需查看命令摘要，请参阅 gcloud beta device-run。
准备工作
以下步骤假定您已完成以下操作：
- 创建了 Google Cloud 项目。
- 按照快速入门设置开发者设备平台。
- 已在终端中使用
gcloud进行身份验证。 - 查看了 Device Run 概览，了解一般信息。
- 为 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 步：配置测试运行
现在，您已经运行了测试，接下来可以探索一些配置选项：
- 多台设备：如需在多台设备上运行相同的测试，请提供
--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 次尝试）。
第 4 步：使用分片
如需在持续集成和持续交付 (CI/CD) 工作流中纳入开发者设备平台，您应考虑对测试进行分片。测试分片旨在将一组测试划分为多个独立运行的子组（分片）。开发者设备平台会自动使用多个设备并发运行各个分片，从而在更短的时间内完成整个测试集。
第 4.1 步。选择分片选项
如果您的作业只有少量测试用例，或者所有测试用例的总执行时间不长，则无需使用分片。如果您有大量测试用例，或者所有测试用例的总执行时间较长，请考虑使用分片。
开发者设备平台同时支持智能分片和统一分片。在决定如何对测试进行分片时，请考虑以下选项：
如果所有测试用例的耗时都差不多，请使用均匀分片，将所有测试用例划分为
n个分片。如果不同测试用例的执行时间差异很大，请使用智能分片。开发者设备平台会使用历史测试作业时间来创建不同的分片，并尝试在相似的时长内完成所有分片。
均匀分片
如需使用均匀分片对测试进行分片，请在 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
该命令会立即返回，因为系统只会将相应会话标记为待取消。取消操作会在后端异步进行。
如果会话已结束，则仅打印当前状态。 请求取消已完成的会话不会导致错误。
后续步骤
接下来，我们将查找和分析日志。