Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

适用于 iOS 的开发者设备平台设备运行

本指南介绍了如何使用 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 retries：设置重新运行不可靠测试的最大尝试次数：--flaky-test-attempts=3（默认值为 1 次尝试）。
自定义 Cloud Storage 存储桶：为输入和输出指定自定义 Cloud Storage 存储桶：--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/Build/Products

2. 验证 build 产品和签名

构建完成后，验证应用、运行程序和 .xctestrun 清单是否已在 ./build/Build/Products/ 下生成。如果是在本地签名，您可以使用 codesign 验证 bundle 签名：

验证 app bundle：

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 归档文件

将 build 输出 products 文件夹中的 Debug-iphoneos 目录和 .xctestrun 文件压缩到一个 ZIP 归档文件中。

从 build products 目录运行以下命令：

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

后续步骤

接下来，查找和分析日志。