Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Developer Device Platform Device Run for Android Instrumentation

本指南說明如何使用 gcloud beta device-run CLI 執行 Android 檢測設備測試，並在 Google Cloud 控制台中查看結果。並假設您已有 Google Cloud 帳戶和專案。

如要從 Firebase Test Lab 遷移至 Developer Device Platform，請參閱遷移指南、指令和旗標對照表，以及 AI 代理的遷移技能。

如要使用這項 Google Cloud CLI，您必須提供 Google Cloud 專案 ID。如需指令摘要，請參閱 gcloud beta device-run。

事前準備

這些步驟假設您已完成下列事項：

已建立 Google Cloud 專案。
按照快速入門導覽課程設定 Developer Device Platform。
已在終端機中使用 gcloud 進行驗證。
查看Device Run 總覽，瞭解一般資訊。
建構 Android 檢測設備測試。

步驟 1：設定測試執行作業

Android 檢測設備測試選項

多部裝置：如要在多部裝置上執行同一項測試，請提供 --device 旗標，並以半形逗號分隔多個裝置 ID (例如 --device shiba-34,tokay-36)，或提供多個 --device 旗標，每個旗標指定不同的裝置 ID (例如 --device shiba-34 --device tokay-36)。
將檔案推送至裝置：在執行前，使用 --other-files-to-push=SOURCE=DEST,... 將其他檔案 (例如機器學習模型權重、測試輸入或 .so 共用程式庫) 推送至裝置。SOURCE 支援本機路徑和 Cloud Storage (gs://...) 路徑，而 DEST 是裝置上的目的地路徑。
從裝置提取檔案：執行完成後，使用 --paths-to-pull=DEVICE_PATH,... 從裝置提取產生的檔案或目錄。
自訂 Cloud Storage bucket：使用 --bucket-name= 指定現有的 Cloud Storage bucket 名稱 (不含 gs:// 配置或路徑)。如未指定 bucket，Google Cloud CLI 會使用或建立名為 PROJECT_ID-devicerun 的預設 bucket。
不穩定測試重試：設定每項工作或 shard 的重試次數上限，以處理不穩定問題：--flaky-test-attempts=3 (預設為 1 次)。
裝置環境和診斷：設定裝置螢幕方向 (--orientation=portrait 或 landscape)、語言代碼 (--locale=en-US)、模擬 GPS 位置 (--coordinates=LATITUDE,LONGITUDE)、螢幕錄影 (--video=always 或 on-failure)、dumpsys 收集 (--dumpsys=always 或 on-failure) 或 bugreport 收集 (--bugreport=always 或 on-failure)。
標籤：使用 --labels=KEY=VALUE,... 將使用者定義的鍵/值標籤附加至工作階段。
其他應用程式：您可以選擇指定一或多個 APK、AAB 或 APKS 檔案，以便在使用 --apps=path1,path2,...,path_n 旗標執行測試前安裝。系統會按照您指定的順序安裝這些應用程式。
測試逾時：限制執行時間長度：--instrumentation-timeout=10m (有效範圍為 1m 至 3h，預設值為 5m)。

同步和非同步執行

根據預設，提交指令會封鎖 (同步)。系統會等待測試完成，並列印結果摘要表。

如要在將檔案上傳至 Cloud Storage 後立即提交工作階段並返回，請新增 --async 旗標：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

這項操作會立即傳回工作階段 ID。接著，您可以使用 sessions wait 指令等待作業完成：

gcloud beta device-run sessions wait SESSION_ID

指令會封鎖，直到工作完成為止。

多部裝置

如要在多部裝置上執行相同測試，請提供 --device 旗標，並以半形逗號分隔多個裝置 ID，或提供多個 --device 旗標，每個旗標指定不同的裝置 ID：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

或：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

測試逾時

限制測試的執行時間：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

有效範圍為 1m 至 3h，預設值為 5m。

軟體版本

探索並使用可用的軟體套件和 AndroidX Test Orchestrator 版本，並在設定測試執行前檢查其生命週期、支援的版本和中繼資料。

首先，列出所有可用的軟體套件及其版本：

gcloud beta device-run software-versions list

輸出內容大致如下：

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

接著，使用清單中的確切資源 ID 描述特定套件：

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

輸出內容大致如下：

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

現在您已知道可用的軟體版本，可以使用 --orchestrator-version 旗標在測試執行中使用這些版本，如下所示：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

啟用自動化調度管理工具

Developer Device Platform 支援 Android Test Orchestrator，可讓您在應用程式測試叫用的 Instrumentation 中執行每項測試。

使用 Orchestrator 時，您可以：

避免共用狀態。每項測試都會在各自的 Instrumentation 執行個體中執行。因此，如果測試共用應用程式狀態，大部分共用狀態會在每次測試後，從裝置的 CPU 或記憶體中移除。如要在每次測試後，從裝置的 CPU 和記憶體中移除所有共用狀態，請加入 clearPackageData 設定，如下所示：--additional-test-options clearPackageData=true
隔離當機問題。即使有一個測試停止運作，也只會終止自己的 Instrumentation 執行個體，這表示其他測試仍會執行，並提供完整的測試結果。

Developer Device Platform 預設會關閉 Android Test Orchestrator。如要啟用 Orchestrator 並指定測試執行期間使用的版本，請將所選版本傳遞至 sessions submit instrumentation 指令中的 --orchestrator-version=ORCHESTRATOR_VERSION 旗標，如下所示：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

將旗標設為 auto，即可使用系統預設的 Orchestrator 版本。

步驟 2：選擇裝置

使用 device-run CLI，即可在可用的實體和虛擬裝置上執行 Android 測試。如要查看可用裝置的完整清單，請前往互動式裝置目錄，或執行下列指令：

gcloud beta device-run devices list

輸出內容範例：

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

請參閱裝置目錄，瞭解如何篩選這份清單。如要指定特定裝置執行，請在提交指令中使用對應的 ID (例如 tegu-35)。

步驟 3：執行測試

提交 Android 檢測設備測試 APK。

Android 檢測設備測試需要下列旗標：

裝置：使用 --device 指定裝置：--device shiba-35
測試：使用 --test 指定測試 APK：--test /path/to/test.apk

如要執行檢測設備測試，請發出類似下列的 sessions submit instrumentation 指令，並使用您自己的裝置 ID 和測試路徑：

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

您可以在 Cloud Storage 路徑 (例如 gs://BUCKET_NAME/automation/sessions/SESSION_ID/) 找到工作的結果報表資料夾。請查看指令輸出內容，找出類似 https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/ 的連結。

步驟 4：使用 sharding

如要在持續整合和持續推送軟體更新 (CI/CD) 工作流程中，加入 Developer Device Platform 檢測設備測試，建議您將測試進行資料分割。測試資料分割會將一組檢測設備測試分成多個子群組 (資料分割)，並分別獨立執行。Developer Device Platform 會自動使用多部裝置平行執行每個 shard，並在更短的時間內完成整組測試。

步驟 4.1. 選擇 sharding 選項

如果工作只有少量測試案例，或所有測試案例的總執行時間不長，則不需要使用資料分割。如果您有大量測試案例，或所有測試案例的總執行時間很長，建議使用資料分割。

Developer Device Platform 支援智慧型和統一型資料分割。決定如何將測試進行資料分割時，請考量下列選項：

如果所有測試案例所需時間相近，請將所有測試案例分成 n 個 shard，使用統一 shard。
如果不同測試案例的執行時間差異很大，請使用智慧型分區。Developer Device Platform 會根據歷來測試執行時間建立不同的 shard，並嘗試在相近的時間內完成所有 shard。

統一 sharding

如要使用統一資料分割功能分割測試，請在 sessions submit instrumentation 指令中加入 --sharding-option=uniform 和 --uniform-sharding-count= 旗標，如下所示：

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

您應該會看到輸出內容顯示 Job status: 2 running。服務會建立兩項工作，每部裝置各一項。由於兩項工作的輸入內容相同，服務會集中驗證，只執行一次。

指令完成後，您會在最終輸出內容中看到兩項工作分別列出：

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

智慧型資料分割

如要使用智慧型資料分割功能分割測試，請在 sessions submit instrumentation 指令中加入 --sharding-option=smart、--smart-sharding-max-shard-count=、--smart-sharding-target-duration= (以分鐘或 1h 為單位) 和 --smart-sharding-record-name= 旗標，如下所示：

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

您應該會看到最終輸出內容，指出已執行三項工作：

Session [session-3cd0564a] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED
job-002   execution-000   PASSED

以下摘要說明這裡使用的智慧型 sharding 旗標：

--smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT：指定要為智慧型資料分割建立的資料分割數量上限。如未設定或設為 0，系統會使用預設上限。實體裝置的有效範圍為 0 到 20，虛擬裝置則為 0 到 200。
--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION：指定智慧型分區中每個分區的目標執行時間 (例如 2m、10m、1h)。有效範圍為 2 分鐘到 1 小時。--sharding-option=smart 時為必填。
--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME：指定智慧型 sharding 記錄檔的名稱，不含副檔名。如果 --sharding-option=smart，則為必要。這個 YAML 檔案位於 --bucket-name 指定的 Google CloudStorage bucket 中，路徑為 smart-sharding/ 目錄。如果檔案不存在，系統會自動建立；否則，檔案內容會在工作階段完成時更新。

步驟 5：查看及管理測試執行作業

無論是 sessions submit instrumentation 指令的非同步或同步模式，您都可以使用 sessions describe 指令，在執行期間查詢工作狀態，或在完成後取得結果：

gcloud beta device-run sessions describe SESSION_ID

輸出內容會總結測試結果，並提供 Google Cloud 控制台中的結果連結。例如：

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

使用下列指令，列出所有執行中和已完成的工作階段：

gcloud beta device-run sessions list

輸出內容會列出專案中的工作階段，類似以下內容：

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

sessions list 指令支援所有標準 Google Cloud CLI 旗標選項。例如：

gcloud beta device-run sessions list --limit 5

結果大致如下：

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

如要找出所有執行中的工作階段，請執行：

gcloud beta device-run sessions list --filter RUNNING

假設您有執行中的工作階段，就會看到類似下方的結果：

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

否則，您將收到 Listed 0 items.

如要取消執行中的工作階段，請執行下列指令並附上工作階段 ID：

gcloud beta device-run sessions cancel SESSION_ID

由於工作階段僅標示為取消，因此指令會立即傳回。取消作業會在後端以非同步方式進行。

如果工作階段已結束，系統只會顯示目前狀態。要求取消已完成的工作階段不會發生錯誤。

後續步驟

接下來，請執行 Android 執行檔，或尋找並分析記錄。