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

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

本指南提供了从 Test Lab(或 Flank)到 DDP 的命令行转换和标志映射。请按照本指南手动迁移测试。如需了解自动化工具、优势、主要差异和迁移提示,请参阅从 Firebase Test Lab 迁移到 Developer Device Platform。

分片迁移

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 天的时间元数据:

  • 旧版 Flank:

    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 alpha 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 在发布时没有图形化 Web 界面(如旧版 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 和 gcloud alpha device-run sessions submit xctest 命令的标志映射。

核心参数和素材资源

旧版参数(Test Lab/Flank) 目标 DDP 参数 格式/转换逻辑
侧翼 --project --project 标准 Google Cloud 全局标志 (--project=PROJECT_ID) 或活跃的 Google Cloud CLI 配置。
--client-details --labels 要附加到测试会话的 key=value 对的字典。
--other-files --other-files-to-push 字典。在测试运行之前要推送到设备的辅助文件。将旧版 DEST=SOURCE 顺序反转为 SOURCE=DEST(Android 上为 SOURCE=DEVICE_PATH;iOS 上为 SOURCE=BUNDLE_ID:DEVICE_PATH)。

设备配置和定位

旧版参数(Test Lab/Flank) 目标 DDP 参数 格式/转换逻辑
--device model={M},version={V} --device={M}-{V} 必需字符串,用于将型号和操作系统版本映射到单个 --device ID 字符串。DDP 的 --device 标志接受以英文逗号分隔的多个设备 ID(例如 --device=shiba-34,tokay-36 或 --device=iphone16pro-18-3)或多个 --device 标志,每个标志指定一个不同的设备 ID(例如 --device=shiba-34 --device=tokay-36)。

执行控制和不稳定性

旧版参数(Test Lab/Flank) 目标 DDP 参数 格式/转换逻辑
--async --async Boolean。地图 1:1。默认情况下,命令会同步执行。传递此参数可立即返回终端。在文件上传后立即退出,并输出操作和会话 ID。
--num-flaky-test-attempts {R} --flaky-test-attempts {A} 整数。每个测试分片的执行尝试次数上限。将重试次数 R 转换为总尝试次数 A 限制:A = R + 1(默认值为 1)。

输出和存储

旧版参数(Test Lab/Flank) 目标 DDP 参数 格式/转换逻辑
--results-bucket --bucket-name String。用于上传测试工件(包括本地输入文件、测试输出文件和智能分片时间记录)的 Cloud Storage 存储桶(如果未指定,则默认为 gs://[PROJECT_ID]-devicerun)。
--results-dir 自动管理 不支持。子路径会自动整理到 Cloud Storage 中的 automation/sessions/{session_id}/ 下。
--directories-to-pull --paths-to-pull 列表。测试运行后要从设备下载的文件或目录(在 Android 上为 DEVICE_PATH;在 iOS 上为 BUNDLE_ID:DEVICE_PATH)。

分片配置

旧版参数(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 中 smart-sharding/ 下 --bucket-name 内的分片记录 YAML 的名称(不包括文件扩展名)。

Android 专用标志

使用下表将旧版 gcloud firebase test android run 和 Flank Android 标志映射到其新的 gcloud beta device-run sessions submit instrumentation 等效标志:

测试类型 特征组 旧版参数(firebase android/Flank) 目标 DDP 参数 格式/转换逻辑
通用 Android 核心参数和素材资源 --app --apps 列表。如果提供了多个应用 APK/AAB,请按照在设备上安装的顺序将它们全部传递给 --apps。路径可以是本地路径,也可以是 Cloud Storage (gs://...) 中的路径。
通用 Android 核心参数和素材资源 --additional-apks --apps 列表。将其他列表值直接合并到主 --apps 列表中。
通用 Android 核心参数和素材资源 --obb-files --other-files-to-push SOURCE=DEST 格式的字典。将 OBB 文件直接推送到目标设备路径 (/sdcard/Android/obb/{package_name}/)。
通用 Android 设备配置和定位 --device locale={L} --locale={L} String。将设备语言区域映射到顶级 --locale 标志(language-region,例如 --locale=en-US) to switch the device to before running the test.
通用 Android 设备配置和定位 --device orientation={O} --orientation={O} String。将设备屏幕方向映射到顶级 --orientation 标志(portrait 或 landscape)。
通用 Android 设备配置和定位 不适用 --coordinates String。模拟设备 GPS 位置坐标(例如--coordinates=37.4220,-122.0841)。
通用 Android 执行控制和不稳定性 --grant-permissions 自动默认审查 自动。默认情况下,系统会自动授予运行时权限(相当于 --grant-permissions=all)。
通用 Android 输出和存储 不适用 --dumpsys String。使用 dumpsys 收集系统状态(值:always、on-failure)。
通用 Android 输出和存储 不适用 --bugreport String。从设备收集完整的 bugreport(值:always、on-failure)。
通用 Android 输出和存储 --record-video --video String。何时在测试运行期间录制设备屏幕视频。有效值为 always 或 on-failure。
Android 插桩 核心参数和素材资源 --type=instrumentation sessions submit instrumentation 子命令结构决定了测试类型,而不是 --type 标志。
Android 插桩 核心参数和素材资源 --test --test 必需字符串。包含插桩测试的测试 APK 的路径,可以是本地路径,也可以是 Cloud Storage 中的路径。
Android 插桩 执行控制和不稳定性 --timeout --instrumentation-timeout 时长(例如:10m、20s、1h)。有效范围:1m 到 3h(默认值为 5m)。
Android 插桩 执行控制和不稳定性 不适用 --flaky-test-parallel-retry Boolean。是否并行重试失败的测试(默认为 false,表示依序执行)。
Android 插桩 执行控制和不稳定性 不适用 --flaky-test-retry-level String。定义是在 shard 级别还是在单个 test 级别重试(默认为 shard)。
Android 插桩 测试运行程序和目标 --test-runner-class --test-runner-class String。完全限定的插桩测试运行程序类(例如 com.foo.MyRunner)。如果未指定,系统会通过检查应用的清单来确定默认运行程序类。
Android 插桩 测试运行程序和目标 --test-targets --test-targets 要运行的测试目标或目标过滤条件的字典。每个目标都必须使用支持 package、notPackage、class、notClass、annotation、notAnnotation 和 size 等键的软件包名称或类名称进行完全限定。不支持 testfile 或 notTestfile 格式。
Android 插桩 测试运行程序和目标 --use-orchestrator --orchestrator-version 是否使用 Android Test Orchestrator。接受 auto(默认编排器)或特定版本字符串(例如 1.6)。可以使用 gcloud beta device-run software-versions list 查询可用版本。
Android 插桩 测试运行程序和目标 --environment-variables --additional-test-options 传递给插桩测试运行程序的选项字典。此处不允许使用 --test-targets 中支持的格式。

iOS 专用标志

请使用下表将旧版 gcloud firebase test ios run 和 Flank iOS 标志映射到其新的 gcloud alpha device-run sessions submit xctest 等效标志:

测试类型 特征组 旧版参数(firebase ios/Flank) 目标 DDP 参数 格式/转换逻辑
常见 iOS 核心参数和素材资源 --additional-ipas --additional-apps 在测试运行之前要安装到设备上的辅助 .ipa 文件的列表。
仅限 iOS XCTest 核心参数和素材资源 --type=xctest sessions submit xctest 子命令结构决定了测试类型,而不是 --type 标志(使用 gcloud alpha)。
仅限 iOS XCTest 核心参数和素材资源 --test --test 必需字符串。包含 iOS 应用和 XCTest 文件的 ZIP 文件的路径,可以是本地路径,也可以是 Cloud Storage 中的路径。
仅限 iOS XCTest 执行控制和不稳定性 --timeout --xctest-timeout 时长(例如:5m、15m、1h)。有效范围:1m 到 1h(默认值为 5m)。
仅限 iOS XCTest 输出和存储 --record-video --video 何时录制视频:always或on-failure。系统会为每个界面测试用例录制一个视频(iOS 17 或更高版本)。
仅限 iOS XCTest 测试运行程序和目标 --xctestrun-file --xctestrun-file String。自定义 .xctestrun 文件的路径,可以是本地路径,也可以是 Cloud Storage 中的路径。
仅限 iOS XCTest 测试运行程序和目标 --xcode-version --xcode-version String。要使用的 Xcode 的目录 ID 或版本字符串(例如 xcode-16-4 或 16.4)。可以使用 gcloud beta device-run software-versions list 查询可用版本。

反馈和问题

与我们联系,提交 bug 和功能请求,或加入我们的讨论论坛。