#开始使用：iOS · Vitest · ChatGPT 订阅

本页是在 iOS 上使用 Vitest、通过 ChatGPT 订阅接入模型的配置步骤。如需其他组合，请修改下方的选择，或查看全部配置路径。

第 1 步

#安装 Node.js

安装 Node.js ^20.19.0 || ^22.12.0 || >=24.0.0，并确认终端中可以执行 node -v。

下文命令使用 pnpm。如果尚未安装，请运行 npm install -g pnpm。

第 2 步

#通过 WDA 连接 iOS 设备

Midscene 通过运行中的 WebDriverAgent（WDA）服务与 iOS 真机或模拟器通信。如果 WDA 服务已启动且可从当前电脑访问，可直接跳至确认 WDA 服务状态。

#构建并启动 WebDriverAgent

开始前，请先准备好以下 iOS 开发环境：

• macOS（iOS 开发与真机调试必需）
• Xcode 及 Xcode 命令行工具（Command Line Tools）
• iOS 模拟器或真机设备

请参考 Appium 官方文档完成 WebDriverAgent（WDA）的构建与启动：

• 模拟器配置：Run Prebuilt WDA
• 真机配置：Real Device Configuration

#配置真机并转发端口

iOS 模拟器会直接在 localhost 上监听端口，无需转发；如果使用模拟器或已配置好的远程 WDA 服务，可跳至确认 WDA 服务状态。

使用 iOS 真机时：

1. 使用 USB 数据线将手机连接到 Mac，并在手机弹窗中点击「信任此电脑」。
2. 在手机系统设置中开启开发者模式（「设置 > 隐私与安全性 > 开发者模式」）与 UI Automation（「设置 > 开发者 > Enable UI Automation」）。
3. 完成开发者证书签名并在真机上启动 WDA 后，使用 iproxy（可通过 brew install libimobiledevice 安装）将设备上的 WDA 端口（默认为 8100）转发到 Mac 本机：

iproxy 8100 8100 YOUR_DEVICE_ID

请将 YOUR_DEVICE_ID 替换为真机的实际 UDID，并保持 WDA 与 iproxy 进程持续运行。如果同时连接多台设备或使用了自定义端口，请为每台设备映射独立的本机端口，并在 Playground 或项目配置中填写对应端口。

#确认 WDA 服务状态

在运行 Midscene 的电脑上，通过浏览器或终端访问 WDA 的 /status 接口：

• 本机默认地址：http://localhost:8100/status（若使用自定义端口、远程服务或网关，请访问实际的服务地址）
• 正常响应示例：

{
  "value": {
    "build": {
      "version": "10.1.1",
      "time": "Sep 24 2025 18:56:41",
      "productBundleIdentifier": "com.facebook.WebDriverAgentRunner"
    },
    "os": {
      "testmanagerdVersion": 65535,
      "name": "iOS",
      "sdkVersion": "26.0",
      "version": "26.0"
    },
    "device": "iphone",
    "ios": {
      "ip": "10.91.115.63"
    },
    "message": "WebDriverAgent is ready to accept commands",
    "state": "success",
    "ready": true
  },
  "sessionId": "BCAD9603-F714-447C-A9E6-07D58267966B"
}

返回的 JSON 中包含 "ready": true 即表示 WDA 服务已就绪。请记录该服务的主机地址与端口（或网关地址），以便后续在 Playground 和项目配置中使用。

第 3 步

#使用 ChatGPT 订阅登录

首先，在终端运行：

pnpm dlx @midscene/cli model siwc login

按照终端提示，在浏览器中登录 ChatGPT 并授权使用订阅额度。授权时可以自行设置 Agent 名称；完成后，可在 ChatGPT 的使用情况页面查看已授权的 Agent。

命令会将凭据保存到 ~/.midscene/siwc.json。首次使用前需要手动完成这一步登录。

然后在项目目录中，把以下配置写入 .env 文件。如果还没有项目，请先新建一个目录并在其中运行 pnpm init。

MIDSCENE_MODEL_AUTH_MODE="siwc"
MIDSCENE_MODEL_NAME="gpt-6-sol"
MIDSCENE_MODEL_FAMILY="gpt-6"

可用模型以你的 ChatGPT 账号为准。凭据与额度说明请参阅使用 ChatGPT 订阅。

第 4 步

#搭建项目

在 .env 所在的项目目录中，验证模型配置：

pnpm dlx @midscene/test@latest model verify

如果验证失败，请参阅验证模型连接。

#安装依赖

pnpm add -D vitest dotenv @midscene/ios

#配置 Vitest

新建 vitest.config.ts。如果项目已在使用 Vitest，可以将设备测试配置单独保存为 vitest.device.config.ts，运行时通过 --config vitest.device.config.ts 指定，以免影响现有的单元测试配置。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    include: ['e2e/**/*.test.ts'],
    environment: 'node',
    testTimeout: 90_000,
    hookTimeout: 90_000,
    fileParallelism: false,
    sequence: { concurrent: false },
  },
});

由于模型调用和设备连接耗时较长，请根据实际用例适当调大 testTimeout 与 hookTimeout。在共享同一台设备时，需关闭文件级并行（fileParallelism: false）并保持用例串行执行（sequence.concurrent: false），同时避免在代码中调用 test.concurrent 或 describe.concurrent。相关配置项详见 Vitest 的 fileParallelism、testTimeout 和 hookTimeout 文档。

第 5 步

#编写测试

新建 e2e/settings.test.ts，在 beforeEach 中为每个用例创建新的 Agent，并在 afterEach 中销毁：

import 'dotenv/config';
import { afterEach, beforeEach, test } from 'vitest';
import { agentFromWebDriverAgent } from '@midscene/ios';

let agent: Awaited<ReturnType<typeof agentFromWebDriverAgent>> | undefined;

beforeEach(async () => {
  agent = await agentFromWebDriverAgent({
    wdaHost: 'localhost',
    wdaPort: 8100,
  });
});

afterEach(async () => {
  const currentAgent = agent;
  agent = undefined;
  await currentAgent?.destroy();
});

test('scroll through settings', async () => {
  if (!agent) throw new Error('Agent was not initialized');

  await agent.launch('com.apple.Preferences');
  await agent.aiWaitFor('The Settings app is visible');
  await agent.aiAct('Scroll down one screen');
  await agent.aiAssert('The Settings app is still visible');
});

将 wdaHost 和 wdaPort 替换为已验证可用的 WebDriverAgent 服务地址。连接参数详见 iOS SDK 文档。

dotenv/config 用于从项目的 .env 文件加载模型配置（Playground 中的配置不会自动同步到测试进程）。

当 aiAssert 的断言未通过时，会直接抛出错误，Vitest 随即将其所在用例标记为失败，并继续执行 afterEach 销毁 Agent。你也可以用 aiQuery 等方法提取界面数据，再交给 Vitest 的 expect 进行校验。更多交互与提取方法见 Agent API 参考。

第 6 步

#运行测试并查看报告

pnpm exec vitest run e2e/settings.test.ts

运行后，Vitest 会在终端汇总用例的通过或失败状态；Midscene SDK 则默认在 midscene_run/report/ 下生成各 Agent 的执行报告，并在终端打印报告路径。在浏览器中打开生成的 HTML 报告，即可查看各步骤的截图、AI 执行过程和断言结果。

与 Playwright Test 不同，Vitest 接入直接使用 SDK 内置的报告生成机制，无需额外部署 reporter。Vitest 的测试结果与 Midscene 的 Agent 报告相互独立；如需合并或进一步处理报告文件，请参阅处理报告文件。

测试通过且报告中能看到每一步的截图，即表示模型、运行环境和项目都已正常工作。

第 7 步

#下一步

• 查看更多案例：案例展示收录了各平台的演示视频和完整执行报告。

• 查阅 API：API reference 列出了全部 Agent 方法及其参数。
• 将 AI 调用与代码结合：关键 API 说明了 aiAct、即时操作和洞察类 API 的适用场景。

• 多个测试共用设备：生命周期与设备独占说明了多个测试共用一台设备时如何创建和销毁 Agent。

想尝试其他平台或使用方式？回到顶部修改选择。