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

Android 專用 Developer Device Platform 裝置執行

本指南說明如何使用 gcloud beta device-run CLI 執行 Android 檢測測試或獨立 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 檢測設備測試，或準備好獨立 Android 執行檔 (例如已編譯的 C++ 二進位檔、基準測試執行工具或殼層指令碼)。

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

執行工作階段後，請探索一些設定選項：

檢測設備測試和可執行檔的選項

多部裝置：如要在多部裝置上執行相同測試或可執行檔，請提供 --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。
不穩定測試重試：設定每個工作或分片的嘗試次數上限，以處理不穩定情況：--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,... 將使用者定義的鍵/值標籤附加至工作階段。

檢測設備測試選項

其他應用程式：您可以選擇使用 --apps=path1,path2,...,path_n 標記，指定一或多個要在執行測試前安裝的 APK、AAB 或 APKS 檔案。您指定的順序就是這些應用程式的安裝順序。
測試逾時：限制執行時間： --instrumentation-timeout=10m (有效範圍為 1m 至 3h，預設為 5m)。

Android 可執行檔選項

可執行引數：使用 --executable-args=ARG,... 做為以半形逗號分隔的清單，或重複使用標記，將指令列引數傳遞至可執行檔。每個元素都會成為一個引數，因此請將以空格分隔的指令列改寫為以半形逗號分隔的形式 (例如 --executable-args="--input=a.file,--threads=4")。如要傳遞本身包含半形逗號的引數，請在值前面加上 ^SEP^，指定不同的分隔符號 (例如 --executable-args="^;^--shape=1,224,224,3;--threads=4")。
環境變數：使用 --executable-env-vars=KEY=VALUE,... 在裝置上為可執行程序設定環境變數 (例如 --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib)。
Executable timeout：限制可執行檔的執行時間長度：--executable-timeout=10m (有效範圍為 1m 至 3h，預設值為 5m，不含裝置準備和清理時間)。

同步和非同步執行

根據預設，提交指令會封鎖 (同步)。這項工具會等待測試或可執行檔完成，並列印結果摘要表。

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

Android 檢測設備測試

適用於：

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

Android 可執行檔

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

這會立即傳回工作階段 ID。然後使用 sessions wait 指令等待：

gcloud beta device-run sessions wait SESSION_ID

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

多部裝置

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

Android 檢測設備測試

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

Android 執行檔

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

或：

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

測試和可執行檔逾時

限制測試或執行檔的執行時間長度：

Android 檢測設備測試

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

Android 可執行檔

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

Android 執行作業的有效範圍為 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

詳情請參閱「啟用 Orchestrator」。

啟用自動化調度管理工具

對於檢測測試，開發人員裝置平台支援 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 執行檔。

執行檢測設備測試

請注意，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

執行 Android 可執行檔

如要在 Android 裝置上直接執行獨立可執行檔 (例如已編譯的 C++ 二進位檔、裝置端機器學習基準測試執行器 (如 LiteRT) 或殼層指令碼)，而不將其封裝至 APK，請使用 sessions submit android-executable 指令。

請注意，Android 可執行檔必須使用下列標記：

裝置：使用 --device 指定裝置：--device shiba-35
Executable：使用 --executable 指定可執行檔的本機或 Cloud Storage 路徑：--executable /path/to/my_executable

如要執行可執行檔，請發出類似下列的指令，並使用您自己的裝置 ID 和可執行檔路徑：

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

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

步驟 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= (以分鐘或 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-option=smart，則為必要。這個 YAML 檔案位於 --bucket-name 指定的 Google CloudStorage bucket 中，路徑為 smart-sharding/ 目錄。如果檔案不存在，系統會自動建立；否則，檔案內容會在工作階段完成時更新。

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

無論是 sessions submit instrumentation 和 sessions submit android-executable 指令的非同步或同步模式，您都可以使用 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 專用 Developer Device Platform 裝置執行 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

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

檢測設備測試和可執行檔的選項

檢測設備測試選項

Android 可執行檔選項

同步和非同步執行

Android 檢測設備測試

Android 可執行檔

多部裝置

Android 檢測設備測試

Android 執行檔

測試和可執行檔逾時

Android 檢測設備測試

Android 可執行檔

軟體版本

啟用自動化調度管理工具

步驟 2：選擇裝置

步驟 3：執行測試或可執行檔

執行檢測設備測試

執行 Android 可執行檔

步驟 4：使用分片

步驟 4.1. 選擇分片選項

統一分片

智慧型資料分割

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

後續步驟

Android 專用 Developer Device Platform 裝置執行