Android 專用 Developer Device Platform 裝置執行

本指南說明如何使用 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。

事前準備

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

  1. 建立 Google Cloud 專案。
  2. 按照快速入門設定 Developer Device Platform。
  3. 在終端機中透過 gcloud 進行驗證。
  4. 查看Device Run 總覽，瞭解一般資訊。
  5. 為 Android 建立檢測測試。

步驟 1：選擇裝置

使用 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) in the submit command.

步驟 2：執行檢測設備測試

請注意，Android 測試必須使用下列標記：

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

如要執行測試，請發出類似下列的指令，但要使用您自己的裝置 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/。

步驟 3：設定測試執行

執行測試後，請探索下列設定選項：

  • 多部裝置：如要在多部裝置上執行相同測試，請提供 --device 標記，並以半形逗號分隔多個裝置 ID，例如 --device shiba-34,tokay-36，或提供多個 --device 標記，每個標記指定不同的裝置 ID (例如 --device shiba-34 --device tokay-36)。
  • 其他應用程式：您可以使用 --apps=path1,path2,...,path_n 標記，選擇在執行測試前安裝一或多個 APK。系統會按照您指定的順序安裝這些應用程式。
  • 測試逾時：限制執行時間： --instrumentation-timeout=10m (有效範圍為 1m 至 1h，預設為 5m)。
  • 自訂 Cloud Storage bucket：如果您未使用 --bucket-name= 旗標指定 Cloud Storage bucket，Google Cloud CLI 會使用名為 PROJECT_ID-devicerun 的預設 bucket。
  • 不穩定測試重試：設定重新執行不穩定測試的嘗試次數上限：--flaky-test-attempts=3 (預設為 1 次)。

啟用自動化調度管理工具

開發人員裝置平台支援 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 版本。

步驟 4：使用分片

如要在持續整合和持續推送軟體更新 (CI/CD) 工作流程中加入 Developer Device Platform，請考慮將測試分片。測試資料分割會將一組測試分成數個子群組 (資料分割)，這些子群組會個別執行。開發人員裝置平台會使用多部裝置，自動平行執行每個分片，並在較短時間內完成整組測試。

步驟 4.1：選擇分片選項

如果作業只有少數測試案例，或所有測試案例的總執行時間不長，則不必使用分片。如果您有大量測試案例，或所有測試案例的總執行時間很長，建議使用分片。

Developer Device Platform 支援智慧和統一分片。決定如何將測試分片時，請考慮下列選項：

  • 如果所有測試案例所需時間相近，請將所有測試案例分成 n 個資料分割，使用一致的資料分割。

  • 如果不同測試案例的執行時間差異很大，請使用智慧分片。開發人員裝置平台會根據歷來測試執行時間建立不同的分片，並嘗試在類似的時間內完成所有分片。

統一分片

如要使用統一分片方式將測試分片，請在 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= (以分鐘或 1 小時為單位) 和 --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

以下是這裡使用的智慧分片標記摘要：

  • --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT：指定智慧分片要建立的分片數量上限。如未設定或設為 0，系統會使用系統定義的上限。實體裝置的有效範圍為 0 至 20，虛擬裝置則為 0 至 200。

  • --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - Specify the targeted execution time (e.g., 2m, 10m, 1h) per shard for smart sharding. 有效範圍為 2 分鐘至 1 小時。--sharding-option=smart 時為必填。

  • --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - 指定智慧分片記錄檔的名稱，不含副檔名。當 --sharding-option=smart 時為必要。這個 YAML 檔案位於 smart-sharding/ 目錄下，由 --bucket-name 指定的 Google Cloud儲存空間值區中。如果檔案不存在，系統會自動建立；否則，檔案內容會在工作階段完成時更新。

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

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

如果工作階段已結束，系統只會列印目前狀態。 要求取消已完成的課程並非錯誤。

後續步驟

接下來，請尋找及分析記錄。