> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 开始使用：iOS · Midscene Test · 模型 API Key {#get-started}

本页是在 **iOS** 上使用 **Midscene Test**、通过**模型 API Key** 接入模型的配置步骤。如需其他组合，请查看[全部配置路径](/zh/get-started.md#all-setup-paths)。

## 安装 Node.js
安装 Node.js `^20.19.0 || ^22.12.0 || >=24.0.0`，并确认终端中可以执行 `node -v`。
下文命令使用 pnpm。如果尚未安装，请运行 `npm install -g pnpm`。

## 通过 WDA 连接 iOS 设备
Midscene 通过运行中的 WebDriverAgent（WDA）服务与 iOS 真机或模拟器通信。如果 WDA 服务已启动且可从当前电脑访问，可直接跳至[确认 WDA 服务状态](#verify-wda-status)。

### 构建并启动 WebDriverAgent

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

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

:::info 版本要求

WebDriverAgent 版本须 **>= 7.0.0**。

:::

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

- **模拟器配置**：[Run Prebuilt WDA](https://appium.github.io/appium-xcuitest-driver/latest/guides/run-prebuilt-wda/)
- **真机配置**：[Real Device Configuration](https://appium.github.io/appium-xcuitest-driver/latest/getting-started/device-setup/)

### 配置真机并转发端口

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

使用 iOS 真机时：

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

```bash
iproxy 8100 8100 YOUR_DEVICE_ID
```

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

### 确认 WDA 服务状态 {#verify-wda-status}

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

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

```json
{
  "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 和项目配置中使用。

## 创建测试项目

```bash
pnpm dlx @midscene/test create my-tests \
  --platform ios \
  --package-manager pnpm
cd my-tests
```

该命令会生成项目文件、安装依赖并生成 Node 说明书，不会运行测试。生成的文件说明请参阅[项目结构](/zh/midscene-test/use.md#project-structure)。

## 配置模型

在 `my-tests` 目录中，将 `.env.example` 复制为 `.env`：
```bash
cp .env.example .env
```

在下方选择一个模型，它的配置包含四项。点击**获取 API Key**到服务商创建 API Key，再用它替换 `MIDSCENE_MODEL_API_KEY` 中的 `......`。

下方是 Doubao-Seed-2.1 Turbo 的配置。其他推荐模型：

- [Qwen3.7 Plus](/zh/model-api-setup.md#qwen) (阿里巴巴)
- [DeepSeek V4.1 Flash](/zh/model-api-setup.md#deepseek) (深度求索)
- [Gemini 3.5 Flash](/zh/model-api-setup.md#gemini) (Google)
- [GPT-6 Sol](/zh/model-api-setup.md#gpt) (OpenAI)
- [Kimi K3](/zh/model-api-setup.md#kimi) (月之暗面)
- [MiMo V2.6 Pro](/zh/model-api-setup.md#xiaomi-mimo) (小米)
- [GLM-5V-Turbo](/zh/model-api-setup.md#glm-v) (智谱)
- [Ling-3.0-flash-VL](/zh/model-api-setup.md#ant-ling) (蚂蚁集团)

**火山引擎** ([获取 API Key](https://console.volcengine.com/ark))

```bash
MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

**OpenRouter** ([获取 API Key](https://openrouter.ai/settings/keys))

```bash
MIDSCENE_MODEL_BASE_URL="https://openrouter.ai/api/v1"
MIDSCENE_MODEL_API_KEY="......"
MIDSCENE_MODEL_NAME="bytedance-seed/seed-2-1-turbo"
MIDSCENE_MODEL_FAMILY="doubao-seed"
```

其他版本与使用说明请参阅[豆包 Seed 系列](/zh/model-api-setup.md#doubao-seed-model)。

各模型的差异请参阅[模型选择指南](/zh/model-selection.md)。UI-TARS 等兼容模型请参阅[使用模型 API Key](/zh/model-api-setup.md#支持的模型)。

用这份配置填写 `.env` 中的四项 `MIDSCENE_MODEL_*` 变量。

## 验证模型并完成配置
运行以下命令，检查模型能否连通、是否与 Midscene 兼容。该命令只读取当前目录下的 `.env`，不需要浏览器或设备：
```bash
pnpm exec midscene-test model verify
```
如果验证失败，请参阅[验证模型连接](/zh/model-config.md#verify-model-connectivity)。

项目默认连接 `localhost:8100` 上的 WDA。如需使用其他地址，请在 `.env` 中设置 `WDA_HOST` 和 `WDA_PORT`；通过网关访问时设置 `WDA_BASE_URL`。

## 运行示例并查看报告

示例会在设备浏览器中打开 React TodoMVC，并先检查列表为空。请保持设备解锁。如果列表中留有之前运行产生的待办事项，请切换到 **All** 并删除全部事项（包括已完成的事项）。

```bash
pnpm test
```
终端会输出测试结果和 `Report:` 报告路径。打开 HTML 报告，选择用例和步骤即可查看截图、输入输出和错误信息。报告默认保存在 `midscene_run/report/` 目录下。
用例通过即表示模型、运行环境和项目都已正常工作。运行参数请参阅[运行测试](/zh/midscene-test/running.md)。

## 下一步
- **查看更多案例**：[案例展示](/zh/showcases.md)收录了各平台的演示视频和完整执行报告。

- **测试自己的应用**：在 `cases/todo.yaml` 中，将 `beforeEach` 里的 TodoMVC 初始化步骤替换为打开应用的 `launch` Node：

  ```yaml
  beforeEach:
    - launch: com.example.app

  cases:
    - name: 打开首页
      steps:
        - aiAssert: 应用首页已显示
  ```

  Android 使用包名，iOS 使用 Bundle ID，HarmonyOS 使用 bundle name。其他系统操作请参阅[各平台预置 Node](/zh/midscene-test/builtin-nodes.md)。

- **编写和组织用例**：[编写 YAML 用例](/zh/midscene-test/writing.md)介绍了输入、变量、标签和 hooks。
- **在 CI 中运行**：请参阅[在 GitHub Actions 中运行](/zh/midscene-test/running.md#在-github-actions-中运行)。