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」。

Shard 遷移

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

範例：遷移複雜的側翼 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 和 gcloud alpha device-run sessions submit xctest 指令的旗標對應。

核心參數和素材資源

舊版參數 (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} 字串和整數。合併旗標設定可啟用統一 shard 策略，並設定 shard 數量上限 (有效數量範圍：實體 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 內 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 字串。
--device locale={L} --locale={L} 目標語言代碼字串 (language-region，例如 --locale=en-US)。
--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)。

意見回饋與疑問

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