使用 Google Cloud CLI 進行測試

本指南說明如何使用 gcloud CLI 執行 XCTest 或 Game Loop 測試。

步驟 1：設定本機 Google Cloud SDK 環境

下載 Google Cloud SDK

包括 gcloud CLI 工具。

請確認安裝的是最新版本，且包含 gcloud firebase 指令：
```
      gcloud components update
```
使用 Google 帳戶登入 gcloud CLI：
```
      gcloud auth login
```
在 gcloud 中設定 Firebase 專案，其中 PROJECT_ID 是 Firebase 專案的 ID：
```
     gcloud config set project PROJECT_ID
```

步驟 2：執行測試

執行 XCTest

請執行下列指令，上傳測試的 .zip 檔案 (如果您尚未封裝應用程式，請參閱「封裝 XCTest」)：

cd FOLDER_WITH_TEST_OUTPUT/Build/Products ; \
zip -r MyTests.zip Debug-iphoneos YOUR_SCHEME_iphoneosDEPLOYMENT_TARGET-arm64.xctestrun

選擇測試維度。

Test Lab 可讓您在各種 iOS 版本、裝置、螢幕方向和語言代碼上執行測試。這些設定稱為測試的測試維度。如要查看各個維度的選項 (例如裝置 iOS 版本支援的 Xcode 版本)，請在下列指令中將 dimension 替換為 models、versions 或 locales：
```
gcloud firebase test ios dimension list
```
螢幕方向的設定比較簡單，因為只有 portrait 和 landscape 兩個選項。

查看測試維度清單，然後選取要執行測試的幾個組合。請參閱價格方案，瞭解每天可執行的組合上限。

注意：每個維度的 list 表格都包含 TAGS 欄，其中一個資料列標記為 default。如果您未指定該維度的值，Test Lab 就會使用該列。
選擇一組測試維度後，您可以使用 firebase test ios run 指令讓 Test Lab 執行測試。針對您要測試的每個測試維度組合，加入個別的 --device 旗標：
```
gcloud firebase test ios run --test PATH/TO/MyTests.zip \
 --device model=MODEL_ID_1,version=VERSION_ID_1,locale=LOCALE_1,orientation=ORIENTATION_1 \
 --device model=MODEL_ID_2,version=VERSION_ID_2,locale=LOCALE_2,orientation=ORIENTATION_2 \
 etc...
```
由於測試建立時使用的 Xcode 版本與 Test Lab 使用的預設 Xcode 版本不相容，因此測試可能會失敗。如要為測試指定支援的 Xcode 版本，請使用 --xcode-version 標記：
```
gcloud firebase test ios run --test PATH/TO/MyTests.zip \
 --device model=MODEL_ID_1,version=VERSION_ID_1,locale=LOCALE_1,orientation=ORIENTATION_1 \
 --xcode-version=15
```
如要協助您在 Firebase 控制台中識別及找出測試矩陣，您可以選擇使用 --client-details matrixLabel="<label>" 旗標為測試矩陣加上標籤，如以下範例所示：
```
gcloud beta firebase test ios run --test PATH/TO/MyTests.zip \
  --device model=MODEL_ID_1,version=VERSION_ID_1,locale=LOCALE_1,orientation=ORIENTATION_1 \
  --client-details matrixLabel="my label"
```
注意： 只有 gcloud CLI 的 Alpha 版和 Beta 版支援 --client-details 標記。

測試特殊授權

如要測試需要明確應用程式 ID 的授權，您可以設定 --test-special-entitlements 標記。Test Lab 會使用新的套件 ID 重新簽署應用程式，以支援特殊授權，因此請確認 ZIP 檔案中沒有任何資源含有應用程式套件 ID 的直接參照。

支援的授權：

推播通知 apns-environment
個人 VPN com.apple.developer.networking.vpn.api

推播通知

如要授權推播通知要求，使用者可以使用私密簽署金鑰，搭配金鑰 ID (C7FD9DJAA8) 和團隊 ID (9CKCGNNUQN) 建立 JSON Web 權杖。產生的權杖有效時間為 1 小時，需要每 60 分鐘重新整理一次。如要進一步瞭解如何建立與 APN 的符記連線，請參閱這篇文章

應用程式群組

應用程式群組 ID 是全域唯一的 ID。也就是說，當我們重新簽署使用者應用程式時，只能使用與 Test Lab 開發人員帳戶相關聯的應用程式群組 ID。如果測試依賴應用程式群組，則測試會失敗。

執行遊戲迴圈測試

執行 gcloud beta firebase test ios run 指令，並使用下列旗標設定執行作業：

遊戲迴圈測試的旗標
`--type`	必要：指定要執行的 iOS 測試類型。您可以輸入測試類型 `xctest` (預設) 或 `game-loop`。
`--app`	必填：應用程式 IPA 檔案的絕對路徑 (GCS 或檔案系統)。這個旗標僅在執行 Game Loop 測試時有效。
`--scenario-numbers`	您要在應用程式中執行的迴圈 (又稱為情境)。您可以輸入一個迴圈、迴圈清單或迴圈範圍。預設迴圈為 1。例如，`--scenario-numbers=1-3,5` 會執行迴圈 1、2、3 和 5。
`--device-model`	您要執行測試的實體裝置 (瞭解您可以使用的可用裝置)。
`--timeout`	測試執行的時間上限。您可以輸入整數來表示時間長度 (以秒為單位)，也可以輸入整數和列舉，以較長的時間單位表示時間長度。例如： `--timeout=200` 會在測試執行時間達到 200 秒時強制終止測試。 `--timeout=1h` 會在測試執行時間達一小時時強制終止測試。

舉例來說，下列指令會執行遊戲迴圈測試，在 iPhone 8 Plus 上執行 1、4、6、7 和 8 個迴圈：

gcloud beta firebase test ios run
 --type game-loop --app path/to/my/App.ipa --scenario-numbers 1,4,6-8
 --device-model=iphone8plus

如要進一步瞭解 gcloud CLI，請參閱參考說明文件。

步驟 3 (選用)：自動執行您日後建構的測試

使用 Test Lab 編寫 gcloud 指令

您可以使用 Shell 指令碼或批次檔案，自動執行原本要透過 gcloud 指令列執行的行動應用程式測試指令。這個範例 bash 指令碼會以兩分鐘的逾時時間執行 XCTest，並回報測試執行作業是否順利完成：

if gcloud firebase test ios run --test MyTest.zip --timeout 2m
then
    echo "Test matrix successfully finished"
else
    echo "Test matrix exited abnormally with non-zero exit code: " $?
fi

指令碼結束程式碼

Test Lab 提供多個結束碼，可協助您進一步瞭解使用指令碼或批次檔案執行的測試結果。

結束代碼	附註
0	所有測試執行作業均已通過。
1	發生一般錯誤。可能的原因包括：檔案名稱不存在或 HTTP/網路錯誤。
2	測試已結束，因為系統提供不明的命令或引數。
10	測試執行期間，一或多個測試案例 (測試的類別或類別方法) 未通過。
15	Firebase Test Lab 發生未預期的錯誤，因此無法判斷測試矩陣是否通過或失敗。
19	使用者已取消測試矩陣。
20	發生測試基礎架構錯誤。

步驟 4：調查測試結果

測試開始後，您會收到「測試結果」頁面的連結。測試可能需要花費數分鐘才能執行，具體取決於您選取的不同設定數量，以及為測試設定的測試逾時時間長度。測試執行完畢後，您可以查看測試結果。請參閱「分析 Firebase Test Lab 結果」，進一步瞭解如何解讀測試結果。

下一步

請參閱 Google Cloud SDK 說明文件，瞭解正式版或β版的測試選項。