本指南說明如何使用 gcloud alpha
device-run CLI 執行 iOS XCTest，並在 Google Cloud 控制台中查看結果。並假設您已有 Google Cloud 帳戶和專案。
如要從 Firebase Test Lab 遷移至 Developer Device Platform，請參閱遷移指南、指令和旗標對照表，以及 AI 代理的遷移技能。
如要使用 device-run CLI，您必須提供 Google Cloud專案 ID。如需指令摘要，請參閱 gcloud alpha
device-run。
事前準備
這些步驟假設您已完成下列事項：
- 已建立 Google Cloud 專案。
- 按照快速入門導覽課程設定 Developer Device Platform。
- 已在終端機中使用
gcloud進行驗證。 - 查看Device Run 總覽，瞭解一般資訊。
- 編譯測試並封裝成 ZIP 檔案。
步驟 1：設定測試執行作業
您可以使用下列選用旗標自訂測試執行作業 (但至少須使用一個 --device 旗標)：
- 多部裝置：多次指定
--device旗標，即可同時在多部裝置上執行同一項測試：--device iphonese3-18-4 --device iphonese3-26-3或--device iphonese3-18-4,iphonese3-26-3 - 其他應用程式：使用
--additional-apps啟動測試前，請先安裝一或多個額外的.ipa套件：--additional-apps=/path/to/AdditionalApp.ipa - 自訂
.xctestrun檔案：使用--xctestrun-file傳遞自訂設定檔：--xctestrun-file=/path/to/CustomTests.xctestrun - Apple Xcode 版本：使用
--xcode-version旗標直接存取 CLI 支援的 Xcode 版本，例如：--xcode-version=xcode-16-4 - 測試逾時：限制執行時間長度：
--xctest-timeout=10m(有效範圍為1m至1h，預設值為5m)。 - 標籤：將使用者定義的中繼資料附加至工作階段：
--labels=env=staging,owner=my-team - 語言代碼：設定裝置語言代碼：
--locale=en-US - 將檔案推送至裝置：在執行測試前，將檔案推送至應用程式資料容器：
--other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt - 從裝置提取檔案：在測試執行後，從應用程式資料容器提取檔案：
--paths-to-pull=com.example.app:/Documents/output.txt - 不穩定測試重試：設定重新執行不穩定測試的嘗試次數上限：
--flaky-test-attempts=3(預設為 1 次)。 - 自訂 Cloud Storage bucket：指定輸入和輸出的自訂 Cloud Storage bucket：
--bucket-name=my-custom-bucket(預設為PROJECT_ID-devicerun)。 - 上傳大型 ZIP 或 IPA 檔案可能相當耗時，因此您可以直接使用 Cloud Storage
gs://路徑參照檔案，節省上傳時間。
同步和非同步執行
根據預設，提交指令會封鎖 (同步)。系統會等待測試完成，並列印結果摘要表。
如要在將檔案上傳至 Cloud Storage 後立即提交工作階段並返回，請新增 --async 旗標：
gcloud alpha device-run sessions submit xctest \
--device iphonese3-18-4 \
--test ./IOS_TESTS.zip \
--async
這項操作會立即傳回工作階段 ID。接著，您可以使用 sessions wait 指令等待作業完成：
gcloud alpha device-run sessions wait SESSION_ID
指令會封鎖，直到工作完成為止。
多部裝置
如要在多部裝置上執行相同測試，請提供 --device 旗標，並以半形逗號分隔多個裝置 ID，或提供多個 --device 旗標，每個旗標指定不同的裝置 ID。
以半形逗號分隔
gcloud alpha device-run sessions submit xctest \
--device iphonese3-18-4,iphonese3-26-3 \
--test ./IOS_TESTS.zip
多個標記
gcloud alpha device-run sessions submit xctest \
--device iphonese3-18-4 \
--device iphonese3-26-3 \
--test ./IOS_TESTS.zip
測試逾時
限制測試的執行時間：
gcloud alpha device-run sessions submit xctest \
--device iphonese3-18-4 \
--test ./IOS_TESTS.zip \
--xctest-timeout=10m
有效範圍為 1m 至 1h，預設值為 5m。
軟體版本
在設定測試執行作業前，探索並使用可用的軟體套件和 Apple Xcode 版本，並檢查其生命週期、支援版本和中繼資料。
首先，列出所有可用的軟體套件及其版本：
gcloud alpha 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 alpha device-run software-versions describe xcode-16-4
輸出內容大致如下：
id: xcode-16-4
lifecycle:
state: ACTIVE
name: Xcode 16.4
softwareType: XCODE
supportedIosVersions:
- '15.0'
- '15.1'
- '15.2'
- '15.4'
- '15.7'
- '16.0'
- '16.1'
- '16.2'
- '16.3'
- '16.5'
- '16.6'
- '18.0'
- '18.3'
- '18.4'
version: '16.4'
現在您已知道可用的軟體版本，可以使用 --xcode-version 旗標在測試執行中使用這些版本，如下所示：
gcloud alpha device-run sessions submit xctest \
--device iphonese3-18-4 \
--test ./IOS_TESTS.zip \
--xcode-version=16.4
步驟 2：選擇裝置類型
您可以使用 device-run CLI，在可用的實體裝置上執行 iOS 測試。如要查看可用裝置的完整清單，請前往互動式裝置目錄，或執行下列指令：
gcloud alpha device-run devices list
輸出內容範例：
ID MAKE NAME MODEL HARDWARE_TYPE OS_VERSION CAPACITY AVAILABILITY PRODUCTS
iphonese3-18-4 Apple iPhone SE 3 iphonese3 PHYSICAL 18.4 NONE NONE Automation
iphonese3-26-3 Apple iPhone SE 3 iphonese3 PHYSICAL 26.3 NONE NONE Automation
請參閱裝置目錄，瞭解如何篩選這份清單。如要指定特定裝置執行測試，請使用對應的 ID (例如 iphonese3-18-4)。
步驟 3：準備及封裝 XCTest
執行測試前，您必須先編譯測試、確認測試已簽署、驗證程式碼簽章，並將產生的構件封裝成 ZIP 檔案，其中包含 .xctestrun 設定和應用程式測試套件。
1. 建構實體 iOS 裝置測試
在 Xcode 中開啟專案，並建構應用程式和測試目標，以便進行測試：
- 請確認 Xcode 中的程式碼簽署設定正確無誤 (指定有效的佈建設定檔和開發人員身分)，適用於應用程式目標和測試執行工具目標。
使用 Xcode (依序點選「Product」>「Build For」>「Testing」) 或
xcodebuild建構測試。工作區：
xcodebuild build-for-testing \ -workspace YourProject.xcworkspace \ -scheme YourScheme \ -derivedDataPath ./build \ -destination "generic/platform=iOS"獨立專案：
xcodebuild build-for-testing \ -project YourProject.xcodeproj \ -scheme YourScheme \ -derivedDataPath ./build \ -destination "generic/platform=iOS"
這會在 ./build/Build/Products 下產生建構產品
2. 驗證建構產品和簽章
建構完成後，請確認應用程式、執行工具和 .xctestrun 資訊清單已在 ./build/Build/Products/ 下產生。如果是在本機簽署，可以使用 codesign 驗證套件簽章：
驗證應用程式套件：
codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp.app預期輸出內容：
YourApp.app: valid on disk如果執行 XCUITest，也請驗證測試執行器套件：
codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp-Runner.app預期輸出內容：
YourApp-Runner.app: valid on disk
3. 建立 ZIP 封存檔
將建構輸出產品資料夾中的 Debug-iphoneos 目錄和 .xctestrun 檔案壓縮成單一 ZIP 封存檔。
從建構產品目錄執行下列指令：
cd ./build/Build/Products
zip -r MyTests.zip Debug-iphoneos *.xctestrun
這會建立封裝的 MyTests.zip，可與 --test 旗標搭配使用。
步驟 4：執行 XCTest
請注意，下列旗標為必填：
- 裝置：使用
--device指定裝置：--device iphonese3-18-4 - 測試：使用
--test指定測試 ZIP 檔案：--test ./MyTests.zip
如要執行 XCTest，請使用 gcloud alpha device-run sessions submit xctest 指令。您必須提供上一步編譯的測試 ZIP 檔案 (MyTests.zip)。
如要執行基本測試工作階段，請按照下列步驟操作：
gcloud alpha device-run sessions submit xctest \
--device iphonese3-18-4 \
--test ./MyTests.zip
執行作業開始時，CLI 會顯示建立的工作階段 ID，以及儲存結果的 Cloud Storage 目的地：
Creating session [session-ee78b0ed] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/session-ee78b0ed/].
Waiting for session [session-ee78b0ed] to complete....
步驟 5：查看及管理測試執行作業
您可以使用下列指令，追蹤進行中的執行作業及管理歷來工作階段：
- 描述工作階段：查詢工作階段的即時進度或最終結果：
gcloud alpha device-run sessions describe SESSION_ID新增--full即可查看完整詳細資料，包括裝置分配、執行 ID 和 Cloud Storage 構件路徑。 - 列出工作階段：查看最近執行的工作階段：
gcloud alpha device-run sessions list --limit=10 - 取消工作階段：停止執行中的測試工作階段：
gcloud alpha device-run sessions cancel SESSION_ID - 取消作業：停止待處理或執行中的作業：
gcloud alpha device-run operations cancel OPERATION_ID
後續步驟
接下來，請尋找並分析記錄檔。