此技能可帮助将旧版测试运行配置和工作流（来自 Flank 或 gcloud firebase test）转换为现代的、面向资源的 gcloud
beta device-run CLI 界面。
命令和资源结构映射
Device Run CLI 按资源整理命令：devices、software-versions 和 sessions：
1. 设备目录 (devices)
- 列出设备：
- 旧版：
gcloud firebase test android/ios models list - 新：
gcloud beta device-run devices list [--filter="..."] - 示例：
gcloud beta device-run devices list --filter="platform:android"
- 旧版：
- 描述设备：
- 旧版：
gcloud firebase test android/ios models describe {MODEL} - 新：
gcloud beta device-run devices describe {DEVICE} - 示例：
gcloud beta device-run devices describe redfin-30
- 旧版：
- 检查设备容量和车队可用性：
- 旧版：
gcloud firebase test android/ios list-device-capacities - 新：直接嵌入在设备资源（
availability.capacity和availability.available）中。使用gcloud beta device-run devices describe {DEVICE}进行检查，或使用gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH"直接过滤。
- 旧版：
2. 软件版本 (software-versions)
- 列出支持的软件版本（Xcode 和 Android Test Orchestrator）：
- 旧版：
gcloud firebase test ios xcode-versions list - 新：
gcloud beta device-run software-versions list
- 旧版：
- 描述软件版本：
- 新：
gcloud beta device-run software-versions describe {SOFTWARE_VERSION} - 示例：
gcloud beta device-run software-versions describe xcode-16-4
- 新：
3. 自动化会话 (sessions)
- 提交 Android 插桩：
- 旧版：
gcloud firebase test android run --type=instrumentation ... - 新：
gcloud beta device-run sessions submit instrumentation ...
- 旧版：
- 提交 iOS XCTest：
- 旧版：
gcloud firebase test ios run --type=xctest ... - 新：
gcloud beta device-run sessions submit xctest ...
- 旧版：
- 等待会话完成：
- 旧版：仅同步 CLI 阻塞
- 新：
gcloud beta device-run sessions wait {SESSION}
- 描述 / 检查会话：
- 旧版：在 Firebase 控制台 / Cloud 工具结果中查看网页链接
- 新：
gcloud beta device-run sessions describe {SESSION} [--full]
- 列出过往会话：
- 旧版：在 Web 控制台中查看矩阵历史记录
- 新：
gcloud beta device-run sessions list
- 取消会话：
- 旧版：仅限 Web 控制台（无 CLI 命令）
- 新：
gcloud beta device-run sessions cancel {SESSION}
标志映射参考表
下表列出了旧版 Firebase Test Lab 和 Flank 中的参数与 gcloud beta device-run 中支持的等效参数的对应关系：
| 测试类型 | 功能组 | 旧版参数 (firebase/Flank) | 目标形参 (device-run)
|
格式 / 转换逻辑 |
|---|---|---|---|---|
| 通用（Android 和 iOS） | 核心参数和素材资源 | 侧翼广告 --project
|
--project
|
标准 Google Cloud 全局标志 (--project=PROJECT_ID) 或有效的 Google Cloud CLI 配置。 |
| 通用（Android 和 iOS） | 核心参数和素材资源 | --client-details
|
--labels
|
键值对的字典。 |
| 通用（Android 和 iOS） | 设备配置和定位 | --device
model={M},version={V}
|
--device={M}-{V}
|
将型号和操作系统版本映射到 --device ID 字符串。接受单个标志中的多个设备的逗号分隔列表（例如，--device=mediumphone-arm-32,shiba-36）。 |
| 通用（Android 和 iOS） | 执行控制和不稳定性 | --async
|
--async
|
地图 1:1。命令默认保持同步，传递此参数可立即返回。使用 gcloud beta device-run sessions wait
<SESSION_ID> 进行监控或等待。 |
| 通用（Android 和 iOS） | 执行控制和不稳定性 | --num-flaky-test-attempts
{R}
|
--flaky-test-attempts {A}
|
整数。将重试次数 $R$ 转换为总尝试次数上限：$A = R + 1$（默认值为 1）。 |
| 通用（Android 和 iOS） | 执行控制和不稳定性 | 不适用 | --flaky-test-parallel-retry
|
Boolean。是否并行重试失败的测试（默认为按顺序重试）。 |
| 通用（Android 和 iOS） | 执行控制和不稳定性 | 不适用 | --flaky-test-retry-level
|
字符串。重试级别：shard 或 test（默认为 shard）。
|
| 通用（Android 和 iOS） | 输出和存储 | --results-bucket
|
--bucket-name
|
用于上传测试输出制品的存储桶（默认为 gs://[PROJECT_ID]-devicerun）。 |
| 通用（Android 和 iOS） | 输出和存储 | --results-dir
|
自动管理 | 不支持设置自定义子目录；所有测试工件都会自动整理到 --bucket-name 指定的存储桶内的 automation/sessions/{session_id}/ 下。 |
| 通用（Android 和 iOS） | 输出和存储 | --record-video
|
--video
|
有效值：always 或 on-failure。
|
| 通用（Android 和 iOS） | 输出和存储 | --directories-to-pull
|
--paths-to-pull
|
运行后要从设备拉取的路径的列表。 |
| 通用 Android | 核心参数和素材资源 | --app
|
--apps
|
列表。如果提供了多个应用 APK/AAB，请将它们全部传递给 --apps。 |
| 通用 Android | 核心参数和素材资源 | --additional-apks
|
--apps
|
列表。将其他列表值直接合并到主 --apps 列表中。
|
| 常见 Android | 核心参数和素材资源 | --obb-files
|
--other-files-to-push
|
采用 SOURCE=DEST 格式的字典。将 OBB 文件直接推送到设备路径 (/sdcard/Android/obb/{package_name}/)。 |
| 常见 Android | 核心参数和素材资源 | --other-files
|
--other-files-to-push
|
采用 SOURCE=DEST 格式的字典。
|
| 常见 Android | 设备配置和定位 | --device locale={L}
|
--locale={L}
|
将设备语言区域设置映射到顶级 --locale 标志（language-region，例如--locale=en-US）。 |
| 常见 Android | 设备配置和定位 | --device orientation={O}
|
--orientation={O}
|
将设备屏幕方向映射到顶级 --orientation 标志（portrait 或 landscape）。 |
| 通用 Android | 设备配置和定位 | 不适用 | --coordinates
|
模拟位置坐标
(latitude,longitude，例如，
37.4220,-122.0841）。 |
| 通用 Android | 执行控制和不稳定性 | --grant-permissions
|
自动默认审查 | 自动化。默认情况下，系统会自动授予运行时权限（相当于 --grant-permissions=all）。| |
| 通用 Android | 输出和存储 | 不适用 | --dumpsys
|
从设备 (always 或 on-failure) 收集 dumpsys。 |
| 通用 Android | 输出和存储 | 不适用 | --bugreport
|
从设备收集 bug 报告（always 或 on-failure）。 |
| Android Instrumentation | 核心参数和素材资源 | --type=instrumentation
|
sessions submit instrumentation
|
子命令结构决定了测试类型，而不是 --type 标志。
|
| Android Instrumentation | 核心参数和素材资源 | --test
|
--test
|
包含插桩测试的二进制文件的路径。 |
| Android Instrumentation | 执行控制和不确定性 | --timeout
|
--instrumentation-timeout
|
时长（例如，10m、20s、1h）。有效范围：1m 至 3h（默认值为 5m）。 |
| Android Instrumentation | 执行控制和不稳定性 | --num-uniform-shards {N}
|
--sharding-option=uniform--uniform-sharding-count={N}
|
标志配置会激活统一分片策略（有效数量范围：1-20 个物理分片，1-200 个虚拟分片）。 |
| Android Instrumentation | 执行控制和不稳定性 | 侧翼 --shard-time {S}
|
--sharding-option=smart--smart-sharding-target-duration={S}
|
启用以目标执行时间为依据的智能分片（例如，2m、10m、1h）。有效范围：2m 至 1h。 |
| Android Instrumentation | 执行控制和不稳定性 | 侧翼
--smart-flank-gcs-path
|
--smart-sharding-record-name={name}--bucket-name={bucket}
|
automation/smart-sharding/ 下 --bucket-name 内分片记录 YAML 的名称（不含扩展名）。 |
| Android Instrumentation | 执行控制和不稳定性 | 侧翼 --max-test-shards
{N}
|
--smart-sharding-max-shard-count={N}
|
如果启用了智能分片，则映射到最大分片边界（0-20 个物理分片，0-200 个虚拟分片）。 |
| Android Instrumentation | 测试运行程序和目标 | --test-runner-class
|
--test-runner-class
|
完全限定的运行程序类。 |
| Android Instrumentation | 测试运行程序和目标 | --test-targets
|
--test-targets
|
支持 package、notPackage、class、notClass、annotation、notAnnotation 和 size 等键的字典。不支持 testfile 或 notTestfile 等格式。 |
| Android Instrumentation | 测试运行程序和目标 | --use-orchestrator
|
--orchestrator-version
|
接受 auto（默认编排器）或特定版本字符串（例如 1.6）。 |
| Android Instrumentation | 测试运行程序和目标 | --environment-variables
|
--additional-test-options
|
传递给测试运行程序的选项的字典。此处不允许使用 --test-targets 中支持的格式。 |
| 常见 iOS | 核心参数和素材资源 | --additional-ipas
|
--additional-apps
|
在测试运行之前要在设备上安装的 .ipa 文件列表。 |
| 常见 iOS | 核心参数和素材资源 | --other-files
|
--other-files-to-push
|
采用 SOURCE=BUNDLE_ID:DEVICE_PATH 格式的字典。 |
| 常见 iOS | 输出和存储 | --directories-to-pull
|
--paths-to-pull
|
测试后要拉取的文件或目录列表，格式为 BUNDLE_ID:DEVICE_PATH。 |
| 仅限 iOS XCTest | 核心参数和素材资源 | --type=xctest
|
sessions submit xctest
|
子命令结构决定了测试类型，而不是 --type 标志。
|
| 仅限 iOS XCTest | 核心参数和素材资源 | --test
|
--test
|
包含 iOS 应用和 XCTest 文件的 ZIP 文件的路径。 |
| 仅限 iOS XCTest | 执行控制和不确定性 | --timeout
|
--xctest-timeout
|
XCTest 运行允许的最大时长（有效范围：1m 到 1h，默认值为 5m）。 |
| 仅限 iOS XCTest | 测试运行程序和目标 | --xctestrun-file
|
--xctestrun-file
|
自定义 .xctestrun 文件的路径。 |
| 仅限 iOS XCTest | 测试运行程序和目标 | --xcode-version
|
--xcode-version
|
要使用的 Xcode 的目录 ID 或版本字符串（例如 xcode-16-4 或 16.4）。使用 software-versions list 进行查询。 |
切实可行的翻译指南
请按照以下准则将 Firebase Test Lab 和 Flank 配置转换为设备运行：
1. 设备规格
在 gcloud beta device-run 中，--device 接受逗号分隔列表形式的模型和版本 ID 字符串。与 Firebase 不同（每个设备需要一个 --device 标志），device-run 允许在一个标志中指定多个设备。设备语言区域设置、屏幕方向和模拟坐标使用单独的顶级标志指定：
- ❌
--device model=MediumPhone.arm,version=32,locale=en,orientation=portrait - ✅
--device=mediumphone-arm-32 --locale=en-US --orientation=portrait
2. 字典和列表
将以逗号分隔的标志转换为列表（--apps、--paths-to-pull）或键值对字典（--other-files-to-push、--additional-test-options）：
- ❌
--other-files /sdcard/file1.txt=local/file1.txt,/sdcard/file2.txt=local/file2.txt - ✅
--other-files-to-push local/file1.txt=/sdcard/file1.txt,local/file2.txt=/sdcard/file2.txt
3. 分片策略
- 均匀分片：
- 设置
--sharding-option=uniform。 - 设置
--uniform-sharding-count={count}（对于实体设备，范围为 1-20；对于虚拟设备，范围为 1-200）。
- 设置
- 智能分片：
- 设置
--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）。
- 设置
4. 异步执行
- 异步和等待：如果指定了
--async，CLI 会立即返回创建的会话 ID。您可以在 CI/CD 工作流中使用以下方法等待会话完成：gcloud beta device-run sessions wait <SESSION_ID>
5. 声明式 YAML 配置 (--flags-file)
对于复杂的配置或偏好于维护版本控制文件而非长终端命令的团队，gcloud 提供了一个通用的 --flags-file 实参预处理器（请参阅 $ gcloud topic flags-file）：
gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml
!注意 为什么键需要
--：gcloud将 YAML 键直接注入到 CLI 解析器中作为命令行标志。YAML 文件中的每个键都必须以--为前缀（例如，--device:、--apps:）。如果没有--，gcloud会将它们作为无法识别的位置实参拒绝。
以下示例演示了多值列表和字典标志：
# 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"
示例翻译
您可以参考这些示例，将现有的 Firebase Test Lab 和 Flank 配置转换为设备运行配置。
Firebase Test Lab 到设备运行
firebase cmd：
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 coverage=true
翻译为：
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 coverage=true
将 Flank 配置传递给设备运行
flank options (flank.yml)：
gcloud:
app: app-debug.apk
test: app-debug-androidTest.apk
device:
- model: mediumphone-arm
version: 32
shard-time: 120
smart-flank-gcs-path: gs://my-bucket/automation/smart-sharding/timing-record.yaml
翻译为：
选项 1：直接调用 CLI（推荐）
直接转换为现代 CLI 命令：
gcloud beta device-run sessions submit instrumentation \
--device=mediumphone-arm-32 \
--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
选项 2：声明性 YAML 标志文件 (--flags-file)
如果您希望在启用了版本控制的 YAML 文件中维护配置，而不是使用 shell 脚本字符串，请使用 gcloud 的内置 --flags-file 功能：
# device-run-flags.yaml
# Note: gcloud requires keys to start with '--'
--device:
- mediumphone-arm-32
--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
使用 CLI 提交：
gcloud beta device-run sessions submit instrumentation --flags-file=device-run-flags.yaml
（您也可以在命令行中附加或替换标志，例如添加 --async）。
设备目录发现
listing & inspecting devices：
# List all available Android devices
gcloud beta device-run devices list --filter="platform:android"
# Filter devices with high fleet capacity (replaces legacy list-device-capacities)
gcloud beta device-run devices list --filter="availability.capacity=CAPACITY_HIGH"
# Describe a specific device (OS versions, form factors, orientation, locales, capacity)
gcloud beta device-run devices describe redfin-30
CI/CD 中的端到端会话生命周期
submitting, waiting, and inspecting sessions：
# 1. Submit asynchronously and capture session ID
SESSION_ID=$(gcloud beta device-run sessions submit instrumentation \
--apps=app-debug.apk \
--test=app-debug-androidTest.apk \
--device=mediumphone-arm-32 \
--async \
--format="value(name)")
# 2. Wait for session completion in CI/CD pipeline
gcloud beta device-run sessions wait "$SESSION_ID"
# 3. Describe session summary (or pass --full for complete details)
gcloud beta device-run sessions describe "$SESSION_ID"
# 4. Cancel a running session if aborted
gcloud beta device-run sessions cancel "$SESSION_ID"