#iOS 环境配置

Midscene 通过 WebDriverAgent（WDA）连接并控制 iOS 设备，支持对原生应用、混合应用及系统界面进行自动化操作。

本文介绍运行 Midscene Test、JavaScript SDK 和 Playground 所需的 iOS 环境配置。你可以先通过 WDA 连接设备，再使用 Playground 验证屏幕截图、触控输入与模型调用。

#通过 WDA 连接设备

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

#1. 构建并启动 WebDriverAgent

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

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

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

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

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

iOS 模拟器会直接在 localhost 上监听端口，无需转发；如果使用模拟器或已配置好的远程 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 或项目配置中填写对应端口。

#3. 确认 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 和项目配置中使用。

#在 Playground 中验证

借助 Playground，无需编写代码即可验证屏幕截图、触控输入与模型调用。

开始前，请参照使用模型 API Key或使用 ChatGPT 订阅准备好模型配置。

#启动 Playground

请确保已安装 Node.js（版本要求 ^20.19.0 || ^22.12.0 || >=24.0.0），且终端中可正常执行 node -v 和 npx --version。

1. 在终端运行以下命令启动 iOS Playground：

npx --yes @midscene/ios-playground

2. 在打开的 Playground 页面中，点击右上角的齿轮图标，粘贴模型配置并保存。
3. 若浏览器未自动打开，请手动访问终端打印的本地地址，并保持该终端进程持续运行。
4. 若页面弹出连接面板，请填写 WDA 的主机地址与端口（本机默认为 localhost 和 8100）并创建 Agent（若本机默认端口上的 WDA 已就绪，Playground 可能会自动完成连接；若通过网关代理访问 WDA，请填写完整的 WebDriverAgent base URL，切勿同时填写 host / port）。
5. 确认预览区域已正常显示当前设备或模拟器的屏幕画面；若画面未显示，请先排查 WDA 连接与端口转发。

#执行操作并验证结果

在 iOS 设备或模拟器上打开 Safari 浏览器，跳过首次启动引导，访问 TodoMVC，并保持设备解锁且浏览器位于前台。

1. 在 Playground 中选择 aiAct，输入以下指令并运行：

添加一个名为“体验 Midscene”的待办事项，然后将它标记为已完成。

2. 待页面中出现已勾选完成的待办事项后，切换到 aiAssert，输入以下断言并运行：

列表中存在名为“体验 Midscene”的待办事项，且它已被标记为完成。

3. 确认断言执行通过，并在结果面板中查看各步骤的截图与执行过程。至此，WDA 连接、屏幕截图、触控输入和模型调用均已验证完毕。

如果执行失败，请结合报错信息排查：若无画面或无法操控设备，请查看下方的常见问题；若模型请求报错，请参考模型连接检查。

#清理体验数据

验证结束后，请在 TodoMVC 页面中删除刚才创建的“体验 Midscene”待办事项。如果接下来要运行 Midscene Test 的 iOS 示例，请切换到 All 视图并确认列表已完全清空（包括已完成事项），因为示例模板在运行前会校验初始列表为空，且不会主动覆盖已有数据。

#效果展示

提示词： 打开美团，帮我下单一杯 Manner 超大杯冰美式咖啡，选择加浓、少冰，并在进入结算页面后等待确认。（完整报告）

#在测试或脚本中使用

完成设备连接与 Playground 验证后，即可将设备接入你的测试或脚本项目：

根据使用场景选择下一步：

• 使用 Midscene Test：前往配置模型与运行环境，完成配置并运行示例（若尚未初始化项目，可先从该页的创建项目开始并选择 iOS 平台）。
• 接入 JavaScript 测试框架：参阅接入 Vitest。
• 编写独立自动化脚本：参阅编写独立自动化脚本中的 iOS 示例。
• 查阅平台 SDK 接口：阅读 iOS JavaScript SDK，了解设备选择、构造参数、平台专属方法与生命周期管理。

#常见问题

#为什么 WebDriverAgent 已连接，但仍无法控制真机设备？

请依次检查真机上的以下设置：

1. 开发者模式：在系统「设置 > 隐私与安全性 > 开发者模式」中确认已开启并重启生效。
2. UI Automation：在系统「设置 > 开发者 > Enable UI Automation」中确认已开启。
3. 电脑信任授权：重新插拔 USB 数据线，确保已在手机弹窗中点击「信任此电脑」。

#iOS 模拟器与真机在使用上有哪些区别？

#模型调用失败

请查看失败步骤的报错信息，并核对 Playground 设置或项目 .env 文件中的模型配置。设备连接正常并不代表模型服务可用，可参照模型连接检查排查 API Key、服务地址或网络问题。注意，命令行与项目运行不会读取浏览器中保存的 Playground 配置，需单独加载项目的环境变量。

#高级连接与调试

#如何自定义 WebDriverAgent 的端口和主机地址？

请参阅 iOS JavaScript SDK。

#如何在 Playground 中获得更流畅的实时投屏画面？

iOS Playground 的屏幕预览支持两种模式：

• 截图轮询模式（默认）：逐帧调用 WDA 截图接口，帧率约为 5～10 fps。
• 原生 MJPEG 流模式（推荐）：直接接入 WDA 内置的 MJPEG Server，帧率更高且延迟更低。

在真机上启用原生 MJPEG 流时，需额外将设备的 9100 端口（WDA MJPEG 默认端口）转发到 Mac 本机（模拟器无需转发）：

iproxy 9100 9100 YOUR_DEVICE_ID

Playground 启动时会自动探测本机 9100 端口：若端口可用，终端会输出 MJPEG: streaming via native WDA MJPEG server 并启用实时流；若不可用，则自动回退为截图轮询模式。