Firebase Test Lab 至開發人員裝置平台指令和旗標翻譯

開發人員裝置平台 (DDP) 整合了舊版 Firebase Test Lab 主控台和 Test Lab CLI 工作流程，並以高效能的統一安全測試 CLI 取代：Google Cloudgcloud beta device-run

本指南提供指令列翻譯，以及從 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} (指向 --bucket-name 內 automation/smart-sharding/ 中的 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)：

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

以下範例說明多值清單和字典旗標：

# 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 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

範例：遷移複雜的側翼 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 不會啟動圖形化網頁 UI (如舊版 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，請將所有 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} 必要字串，可將模型和 OS 版本對應至單一 --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 布林值。是否要並行重試失敗的測試 (依序執行時預設為 false)。
不適用 --flaky-test-retry-level 字串。定義是否要在 shard 或個別 test 層級重試 (預設為 shard)。
--async --async 布林值。地圖 1:1。根據預設，指令會同步執行。傳遞這個值可立即返回終端機。上傳檔案後立即結束，並列印作業和工作階段 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)。如未指定，系統會檢查應用程式的資訊清單，判斷預設執行器類別。
--directories-to-pull --paths-to-pull 清單。測試執行後，要從裝置下載的目錄。
--other-files --other-files-to-push Dictionary 中。以半形逗號分隔的 SOURCE=DEST 清單，列出要在測試執行前推送至裝置的輔助檔案。

輸出內容與儲存空間

舊版參數 (Test Lab / Flank) 目標 DDP 參數 格式 / 轉換邏輯
--results-bucket --bucket-name 字串。測試構件 (包括本機輸入檔案、測試輸出檔案和智慧分片時間記錄) 上傳至的 Cloud Storage bucket (如未指定，預設為 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 個)。
Flank --max-test-shards {N} --sharding-option=smart --smart-sharding-max-shard-count={N} 字串和整數。合併標記設定會啟用智慧分片策略，並設定分片數量上限 (有效數量範圍：實體 0 到 20 個，虛擬 0 到 200 個)。
Flank --shard-time {S} --sharding-option=smart --smart-sharding-target-duration={S} 必填字串。啟用智慧分片功能，並設定目標執行時間 (例如 2m、10m、1h)。有效範圍：2m 至 1h。
Flank --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 bucket。
--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)。

意見回饋與疑問

如要回報錯誤、提出功能要求或加入討論論壇，請與我們聯絡。