#iOS

Midscene 通过 WebDriverAgent 连接 iOS 设备，可自动化 App 和系统界面。

本指南介绍 WebDriverAgent 配置、模型配置、Playground 体验，以及 @midscene/ios 的 JavaScript SDK 集成。

#效果展示

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

查看完整报告，或浏览更多 Midscene 案例。

#快速开始

#准备 iOS 环境

WebDriver 是 W3C 制定的浏览器自动化标准协议。它提供统一的 API，用于控制不同的浏览器和应用。该协议定义了客户端与服务端之间的通信方式，使自动化工具可以跨平台控制界面。

Appium 团队和其他开源社区维护了多种 WebDriver 工具。这些工具可以把桌面端和移动端的自动化操作转换为 WebDriver 协议：

• Appium：跨平台移动自动化框架。
• WebDriverAgent：用于 iOS 设备自动化的服务。
• Selenium：Web 浏览器自动化工具。
• WinAppDriver：Windows 应用自动化工具。

Midscene 支持 WebDriver 协议。你可以使用 AI 模型自动化任何兼容设备。除了点击和输入，Midscene 还可以理解界面上下文、执行多步骤操作、验证结果并提取数据。

在 iOS 上，Midscene 通过 WebDriverAgent 连接设备。连接后，你可以使用自然语言指令控制 iOS App 和系统界面。

继续之前，请确保 WebDriverAgent 可以与设备通信。

#安装 Node.js

安装 Node.js 18 或以上版本。

#配置 WebDriverAgent

在开始之前，你需要先设置 iOS 开发环境：

• macOS（iOS 开发必需）
• Xcode 和 Xcode 命令行工具
• iOS 模拟器或真机设备

配置 WebDriverAgent

在使用 Midscene iOS 之前，需要先准备 WebDriverAgent 服务。

请参考官方文档进行设置：

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

验证 WebDriverAgent

配置完成后，可以通过访问 WebDriverAgent 的状态接口来验证 服务是否启动：

访问地址：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 响应，说明 WebDriverAgent 已经正确配置并运行。

#启动 Playground

Playground 是验证连接的最快方式。无需编写代码，即可体验 aiAct、aiQuery 和 aiAssert 等核心能力。它与 @midscene/ios 共享相同的核心，因此在 Playground 中通过的流程，在脚本中运行会保持一致。

1. 启动 Playground CLI：

npx --yes @midscene/ios-playground

2. 点击窗口中的齿轮按钮进入配置页，粘贴你的 API Key 配置。如果还没有 API Key，请回到 模型配置 获取。

#使用 JavaScript SDK

当 Playground 工作正常后，就可以切换到可复用的 JavaScript 脚本。

#配置模型

通过环境变量设置模型。选择模型时，请参考模型策略。

export MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
export MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
export MIDSCENE_MODEL_NAME="替换为你的模型名称"
export MIDSCENE_MODEL_FAMILY="替换为你的模型系列"

全部配置项请参考模型配置。

#安装依赖

npm install @midscene/ios dotenv --save-dev

yarn add @midscene/ios dotenv --save-dev

pnpm add @midscene/ios dotenv --save-dev

bun add @midscene/ios dotenv --save-dev

deno add npm:@midscene/ios npm:dotenv --save-dev

#编写脚本

下面的示例会在设备上打开 Safari，搜索 eBay，并断言结果列表。

import 'dotenv/config'; // 通过 dotenv/config 自动加载 .env 文件中的环境变量
import {
  IOSAgent,
  IOSDevice,
  agentFromWebDriverAgent,
} from '@midscene/ios';

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
Promise.resolve(
  (async () => {
    // 方式一：直接创建设备和 Agent
    const page = new IOSDevice({
      wdaPort: 8100,
      wdaHost: 'localhost',
    });

    // 👀 初始化 Midscene Agent
    const agent = new IOSAgent(page, {
      aiActionContext:
        'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
    });
    await page.connect();

    // 方式二：使用便捷函数（推荐）
    // const agent = await agentFromWebDriverAgent({
    //   wdaPort: 8100,
    //   wdaHost: 'localhost',
    //   aiActionContext: 'If any location, permission, user agreement, etc. popup appears, click agree. If login page appears, close it.',
    // });

    // 👀 直接打开 ebay.com（推荐做法）
    await page.launch('https://ebay.com');
    await sleep(3000);

    // 👀 输入关键字并执行搜索
    await agent.aiAct('Search for "Headphones"');

    // 👀 等待加载完成
    await agent.aiWaitFor('At least one headphone product is displayed on the page');
    // 或简单地等待几秒：
    // await sleep(5000);

    // 👀 理解页面内容并提取数据
    const items = await agent.aiQuery(
      '{itemTitle: string, price: Number}[], find product titles and prices in the list',
    );
    console.log('Headphone product information', items);

    // 👀 使用 AI 断言
    await agent.aiAssert('Multiple headphone products are displayed on the interface');

    await page.destroy();
  })(),
);

#运行脚本

npx tsx demo.ts

#查看报告

脚本成功后会输出 Midscene - report file updated: /path/to/report/some_id.html。在浏览器中打开对应 HTML 文件即可回放每一步交互、查询与断言。

#API 参考与更多资源

构造函数、辅助方法和平台专属设备 API 位于 API 参考的 iOS 章节。该章节还包含详细参数和自定义操作等进阶内容。跨平台共用的 API 位于通用章节。

#常见问题

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

请检查以下事项：

1. 开发者模式：在“设置 > 隐私与安全性 > 开发者模式”中确认已开启。
2. UI Automation：在“设置 > 开发者 > UI Automation”中确认已开启。
3. 设备信任：确保设备信任当前 Mac。

#模拟器与真机有哪些区别？

#如何自定义 WebDriverAgent 的端口和 Host？

可以通过 IOSDevice 构造函数或 agentFromWebDriverAgent 来指定端口和 Host：

// 方式一：使用 IOSDevice
const device = new IOSDevice({
  wdaPort: 8100,        // 自定义端口
  wdaHost: '192.168.1.100', // 自定义主机
});

// 方式二：使用便捷函数（推荐）
const agent = await agentFromWebDriverAgent({
  wdaPort: 8100,        // 自定义端口
  wdaHost: '192.168.1.100', // 自定义主机
});

针对远程设备，还需要按需设置端口转发：

iproxy 8100 8100 YOUR_DEVICE_ID

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

Playground 的画面预览支持两种模式：

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

要启用原生 MJPEG 流，需要将 WDA MJPEG Server 的端口（默认 9100）转发到本机：

# 真机需要端口转发（模拟器不需要）
iproxy 9100 9100 YOUR_DEVICE_ID

Playground 启动时会自动探测 9100 端口。如果可用，日志会显示 MJPEG: streaming via native WDA MJPEG server；否则自动回退到轮询模式。

#更多

• 查看所有 Agent 方法：API 参考（通用）
• iOS 专属参数与接口：API 参考（iOS）
• 使用 YAML 自动化脚本和命令行工具。
• 示例项目
  • iOS JavaScript SDK 示例：https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo
  • iOS + Vitest 示例：https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo