本指南說明如何使用 gcloud beta device-runCLI 執行 Android 檢測設備測試，並在 Google Cloud 控制台中查看結果。本文假設您已有 Google Cloud 帳戶和專案。
如要使用這個 Google Cloud CLI，您必須提供 Google Cloud 專案
ID。如需指令摘要，請參閱 gcloud beta device-run。
事前準備
這些步驟假設您已完成下列事項：
- 建立專案。 Google Cloud
- 按照快速入門導覽課程設定 Developer Device Platform。
- 在終端機中透過
gcloud進行驗證。 - 查看裝置執行總覽，瞭解一般資訊。
- 為 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) 在提交指令中。
步驟 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 次)。
步驟 4：使用分片
如要在持續整合和持續推送軟體更新 (CI/CD) 工作流程中納入開發人員裝置平台，請考慮將測試分片。測試資料分割會將一組測試分成多個子群組 (資料分割)，這些子群組會個別執行。開發人員裝置平台會使用多部裝置，自動平行執行每個分片，並在較短時間內完成整組測試。
步驟 4.1：選擇分片選項
如果作業只有少量測試案例，或所有測試案例的總執行時間不長，則不必使用分片。如果您有大量測試案例，或所有測試案例的總執行時間很長，建議使用分片。
開發人員裝置平台支援智慧和統一分片。決定如何將測試分片時，請考慮下列選項：
如果所有測試案例所需時間相近，請使用統一分片，將所有測試案例分成
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 CloudStorage bucket 中。如果檔案不存在，系統會自動建立；否則，檔案內容會在工作階段完成時更新。
步驟 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
指令會立即傳回，因為工作階段只會標示為取消。 取消作業會在後端以非同步方式執行。
如果工作階段已結束，系統只會列印目前狀態。 要求取消已完成的課程並非錯誤。
後續步驟
接下來，請尋找及分析記錄。