Firebase Test Lab 到开发者设备平台命令和标志翻译

Developer Device Platform (DDP) 使用统一、高性能且安全的Google Cloud优先测试 CLI：gcloud beta device-run，取代了旧版 Firebase Test Lab 控制台和 Test Lab CLI 工作流

本指南提供了从 Test Lab（或 Flank）到 DDP 的命令行翻译和标志映射。使用本指南手动迁移测试。如需了解自动化工具、优势、主要区别和迁移提示，请参阅从 Firebase Test Lab 迁移到开发者设备平台。

分片迁移

DDP 通过原生替换 Flank 基于 Cloud Storage 的复杂智能分片和 Test Lab 的统一分片，实现了分片配置的现代化。

统一分片

  • 设置 --sharding-option=uniform。

  • 设置 --uniform-sharding-count={count}（对于实体设备，范围为 1-20；对于虚拟设备，范围为 1-200）。

  • 旧版 Firebase Test Lab：--num-uniform-shards {N}

  • DDP CLI：--sharding-option=uniform --uniform-sharding-count={N}

智能分片

  • 设置 --sharding-option=smart。
  • 设置为 --smart-sharding-target-duration={duration}（例如 2m、10m、1h；有效范围：2m 至 1h）。
  • 设置 --smart-sharding-record-name={record_name}（指向 automation/smart-sharding/ 下 --bucket-name 内的 YAML 跟踪记录）。
  • 设置 --smart-sharding-max-shard-count={max_count}（可选上限：实体设备为 0-20，虚拟设备为 0-200）。

使用历史 30 天时间元数据：

  • 旧版侧翼广告：

    max-test-shards: 10
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/smart-sharding/timing-record.yaml

  • DDP CLI：

    --sharding-option=smart \
--smart-sharding-max-shard-count=10 \
--smart-sharding-target-duration=2m \
--smart-sharding-record-name=timing-record \
--bucket-name=my-bucket

声明式 YAML 配置 (--flags-file)

对于复杂的配置或偏好于维护版本控制文件而非长终端命令的团队，gcloud 提供了一个通用的 --flags-file 实参预处理器（请参阅 $ gcloud topic flags-file）：

Android

gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml

iOS

gcloud beta device-run sessions submit xctest --flags-file=device-run-flags.yaml

以下示例演示了多值列表和字典标志：

Android

# device-run-flags.yaml
--device:

    -   mediumphone-arm-32
    -   shiba-36
--apps:
    -   app-debug.apk
    -   test-helper.apk
--test: app-debug-androidTest.apk
--bucket-name: my-bucket
--sharding-option: smart
--smart-sharding-target-duration: 2m
--smart-sharding-record-name: timing-record
--paths-to-pull:
    -   /sdcard/screenshots
    -   /sdcard/coverage.ec
--additional-test-options:
  coverage: "true"
  clearPackageData: "true"

iOS

# device-run-flags.yaml
--device:

    -   iphonese3-18-4
    -   iphone16pro-18-3
--test: MyTests.zip
--additional-apps:
    -   helper-app.ipa
--xcode-version: '16.4'
--xctest-timeout: 15m
--other-files-to-push:
  /local/path/test-config.json: com.example.app:/Documents/test-config.json
--paths-to-pull:
    -   com.example.app:/Documents/screenshots
--labels:
  env: staging
  team: mobile-qa

端到端命令翻译示例

如需查看具体示例，请参阅以下标准翻译和复杂翻译。

示例：运行标准插桩测试

旧版 Firebase CLI：

gcloud firebase test android run \
  --app=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --device model=shiba,version=36 \
  --timeout=5m \
  --num-flaky-test-attempts=2 \
  --directories-to-pull=/sdcard/screenshots \
  --environment-variables key=value

DDP CLI 翻译：

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --instrumentation-timeout=5m \
  --flaky-test-attempts=3 \
  --paths-to-pull=/sdcard/screenshots \
  --additional-test-options key=value

示例：迁移复杂的 flank YAML 配置

旧版 Flank 配置：

app: app-debug.apk
test: app-debug-androidTest.apk
device:
  -   model: shiba
    version: 36
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/smart-sharding/timing-record.yaml

DDP CLI 翻译：

gcloud beta device-run sessions submit instrumentation \
  --device=shiba-36 \
  --apps=app-debug.apk \
  --test=app-debug-androidTest.apk \
  --bucket-name=my-bucket \
  --sharding-option=smart \
  --smart-sharding-target-duration=2m \
  --smart-sharding-record-name=timing-record

执行后和结果检索

由于 DDP 不会启动图形化网页界面（如旧版 Firebase 控制台），因此开发者必须直接使用 CLI 或程序化 REST API 来管理、描述和检查结果：

# 1. List active and completed test sessions
gcloud beta device-run sessions list

# 2. Get a summary and direct Cloud Storage bucket link of a session's results
gcloud beta device-run sessions describe session-number

# 3. Get detailed metadata and print full results
gcloud beta device-run sessions describe session-number --full

# 4. Cancel a running session (replaces console cancellation)
gcloud beta device-run sessions cancel session-number

标志映射参考

下表列出了将测试配置从 Flank 或 gcloud firebase test android/ios run 迁移到新的 DDP gcloud beta device-run sessions submit instrumentation 命令的标志映射。

核心参数和素材资源

旧版参数（Test Lab / Flank） 目标 DDP 参数 格式 / 转换逻辑
--app --apps 列表。如果提供了多个应用 APK/AAB，请按要在设备上安装的顺序将它们全部传递给 --apps。路径可以是本地路径，也可以是 Cloud Storage 路径 (gs://...)。
--test --test 必需的字符串。包含插桩测试的测试 APK 的路径，可以是本地路径，也可以是 Cloud Storage 中的路径。
--client-details --labels 要附加到测试会话的 key=value 对的字典。

设备配置和定位

旧版参数（Test Lab / Flank） 目标 DDP 参数 格式 / 转换逻辑
--device model={M},version={V} --device={M}-{V} 必需的字符串，用于将模型和操作系统版本映射到单个 --device ID 字符串。DDP 的 --device 标志接受以英文逗号分隔的多个设备 ID（例如 --device=shiba-34,tokay-36) 或多个 --device 标志，每个标志指定一个不同的设备 ID（例如 --device=shiba-34 --device=tokay-36)。
--device locale={L} --locale={L} 字符串。将设备语言区域设置映射到顶级 --locale 标志（language-region，例如 --locale=en-US）以在运行测试之前切换设备。
--device orientation={O} --orientation={O} 字符串。将设备屏幕方向映射到顶级 --orientation 标志（portrait 或 landscape）。
不适用 --coordinates 字符串。模拟设备 GPS 位置坐标（例如 --coordinates=37.4220,-122.0841）。

执行控制和不稳定性

旧版参数（Test Lab / Flank） 目标 DDP 参数 格式 / 转换逻辑
--num-flaky-test-attempts {R} --flaky-test-attempts {A} 整数。每个测试分片的最大执行尝试次数。将重试次数 R 转换为总尝试次数 A 上限：A = R +1（默认为 1）。
不适用 --flaky-test-parallel-retry Boolean。是否并行重试失败的测试（默认为 false，表示按顺序执行）。
不适用 --flaky-test-retry-level 字符串。定义是在 shard 级别还是在各个 test 级别进行重试（默认为 shard）。
--async --async Boolean。地图 1:1。默认情况下，命令会同步执行。传递此值可立即返回到终端。在文件上传后立即退出，并打印操作 ID 和会话 ID。

测试运行程序和目标

旧版参数（Test Lab / Flank） 目标 DDP 参数 格式 / 转换逻辑
--environment-variables --additional-test-options 传递给插桩测试运行程序的选项的字典。此处不允许使用 --test-targets 中支持的格式。
--test-targets --test-targets 要运行的测试目标或目标过滤条件的字典。每个目标都必须完全限定，并使用支持键（例如 package、notPackage、class、notClass、annotation、notAnnotation 和 size）的软件包名称或类名称。不支持 testfile 或 notTestfile 格式。
--use-orchestrator --orchestrator-version 是否使用 Android Test Orchestrator。接受 auto（默认编排器）或特定版本字符串（例如 1.6）。您可以使用 gcloud beta device-run software-versions list 查询可用版本。
--test-runner-class --test-runner-class 字符串。完全限定的插桩测试运行程序类（例如 com.foo.MyRunner）来使用。如果未指定，则通过检查应用的清单来确定默认的 runner 类。
--directories-to-pull --paths-to-pull 列表。测试运行后要从设备下载的目录。
--other-files --other-files-to-push 字典。以英文逗号分隔的 SOURCE=DEST 辅助文件列表，用于在运行测试之前推送到设备。

输出和存储

旧版参数（Test Lab / Flank） 目标 DDP 参数 格式 / 转换逻辑
--results-bucket --bucket-name 字符串。用于上传测试制品（包括本地输入文件、测试输出文件和智能分片时间记录）的 Cloud Storage 存储桶（如果未指定，则默认为 gs://[PROJECT_ID]-devicerun）。
--results-dir 自动管理 不支持。子路径会自动整理到 Cloud Storage 中的 automation/sessions/{session_id}/ 下。

分片配置

旧版参数（Test Lab / Flank） 目标 DDP 参数 格式 / 转换逻辑
--num-uniform-shards {N} --sharding-option=uniform --uniform-sharding-count={N} 字符串和整数。组合标志配置既可启用统一分片策略，也可设置最大分片数（有效数量范围：1-20 个物理分片，1-200 个虚拟分片）。
侧翼 --max-test-shards {N} --sharding-option=smart --smart-sharding-max-shard-count={N} 字符串和整数。组合标志配置既可激活智能分片策略，也可设置最大分片数（有效数量范围：0-20 个物理分片，0-200 个虚拟分片）。
侧翼 --shard-time {S} --sharding-option=smart --smart-sharding-target-duration={S} 必需的字符串。启用以目标执行时间为依据的智能分片（例如，2m、10m、1h）。有效范围：2m 至 1h。
侧翼 --smart-flank-gcs-path --smart-sharding-record-name={name} --bucket-name={bucket} 必需的字符串。Cloud Storage 中 --bucket-name 下 smart-sharding/ 内分片记录 YAML 的名称（不含文件扩展名）。

Android 专用标志

使用下表将旧版 gcloud firebase test android run 标志映射到其新的 device-run 等效项：

旧版参数 (firebase android) 目标 DDP 参数 格式 / 转换逻辑
--additional-apks --apps 列表。将其他列表值直接合并到主 --apps 列表中。
不适用 --bugreport 字符串。从设备收集完整的 bugreport（值：always、on-failure）。
不适用 --dumpsys 字符串。使用 dumpsys 收集系统状态（值：always、on-failure）。
--timeout --instrumentation-timeout 时长（例如 10m、20s、1h）。有效范围：1m 至 3h（默认值为 5m）。
--record-video --video 字符串。在测试运行期间录制设备屏幕视频的时间。有效值为 always 或 on-failure。

iOS 专用标志

使用下表将旧版 gcloud firebase test ios run 标志映射到其新的 device-run 等效标志：

旧版参数 (firebase ios) 目标 DDP 参数 格式 / 转换逻辑
--test --test 已构建的 XCTest zip 的路径。
--device model={M},version={V} --device={M}-{V} 目标设备 ID 字符串。
--timeout --xctest-timeout 时长（例如 5m）。范围：1m 至 1h。
--xcode-version --xcode-version 要使用的 Xcode 的目录 ID 或版本字符串（例如 xcode-16-4 或 16.4）。可以使用 gcloud beta device-run software-versions list 查询可用版本。
--results-bucket --bucket-name 自定义目标 GCS 存储桶。
--async --async 默认情况下为同步，传递以立即退出。
--other-files --other-files-to-push 采用 SOURCE=BUNDLE_ID:DEST 格式的字典。
--directories-to-pull --paths-to-pull 以 BUNDLE_ID:DEVICE_PATH 格式列出。
--additional-ipas --additional-apps 测试之前要安装的辅助 IPA 的列表。
--xctestrun-file --xctestrun-file 自定义 .xctestrun plist 的路径。
--num-flaky-test-attempts --flaky-test-attempts 重试次数的整数值（例如 3）。
--client-details --labels 键值对 (KEY=VALUE)。

反馈和问题

您可以与我们联系，提交 bug 和功能请求，也可以加入我们的论坛。