這項技能可協助您將舊版測試執行設定和工作流程 (來自 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 Instrumentation：
- 舊版：
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]
- 列出過往工作階段：
- 舊版：在網頁控制台中查看矩陣記錄
- 新：
gcloud beta device-run sessions list
- 取消工作階段：
- 舊版：僅限網頁版控制台 (沒有 CLI 指令)
- 新：
gcloud beta device-run sessions cancel {SESSION}
旗標對應參考表
下表列出舊版 Firebase Test Lab 和 Flank 的參數，以及 gcloud beta device-run 中支援的對應參數：
| 測驗類型 | 特徵群組 | 舊版參數 (firebase/Flank) | 目標參數 (device-run)
|
格式 / 轉換邏輯 |
|---|---|---|---|---|
| 通用 (Android 和 iOS) | 核心參數和素材資源 | Flank --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
|
布林值。是否要平行重試測試失敗 (預設為循序)。 |
| 通用 (Android 和 iOS) | 執行控制和不穩定性 | 不適用 | --flaky-test-retry-level
|
字串。重試層級：shard 或 test (預設為 shard)。 |
| 通用 (Android 和 iOS) | 輸出內容和儲存空間 | --results-bucket
|
--bucket-name
|
上傳測試輸出構件的 Bucket (預設為 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，請將所有 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
|
從裝置收集 dumpsys (always 或 on-failure)。 |
| 常見 Android 裝置 | 輸出內容和儲存空間 | 不適用 | --bugreport
|
從裝置收集錯誤報告 (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 | 執行控制和不穩定性 | Flank --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 不同，Firebase 每個裝置都需要一個 --device 標記，但裝置執行可讓您在一個標記中指定多部裝置。裝置語言代碼、螢幕方向和模擬座標會使用個別的頂層標記指定：
- ❌
--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}(指向--bucket-name內 YAML 追蹤記錄的指標，位於automation/smart-sharding/下方)。 - 設定
--smart-sharding-max-shard-count={max_count}(選用上限：實體為 0 到 20，虛擬為 0 到 200)。
- 設定
4. 非同步執行作業
- 非同步和等待：指定
--async時，CLI 會立即傳回建立的工作階段 ID。您可以使用gcloud beta device-run sessions wait <SESSION_ID>，在 CI/CD 工作流程中等待工作階段完成：
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 檔案中維護設定，而非使用殼層指令碼字串，請使用 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"