• 简体中文

      • iOS 开始使用

      本指南会带你完成使用 Midscene 控制 iOS 设备的全部步骤：通过 WebDriverAgent 连接真机、配置模型 API Key、体验零代码 Playground，并运行你的首个 JavaScript 脚本。

      示例项目

      使用 JavaScript 控制 iOS 设备：https://github.com/web-infra-dev/midscene-example/blob/main/ios/javascript-sdk-demo

      集成 Vitest 进行测试：https://github.com/web-infra-dev/midscene-example/tree/main/ios/vitest-demo

      配置 AI 模型服务

      将你的模型配置写入环境变量，可参考 模型策略 了解更多细节。

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

      更多配置信息请参考 模型策略 和 模型配置。

      准备工作

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

      准备工作

      安装 Node.js

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

      准备 API Key

      准备一个视觉语言（VL）模型的 API Key。

      你可以在 模型策略 文档中查看 Midscene.js 支持的模型和配置。

      准备 WebDriver 服务

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

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

      配置环境

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

      版本要求

      WebDriverAgent 版本需要 >= 7.0.0

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

      验证环境配置

      配置完成后，可以通过访问 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 是验证连接、观察 AI 驱动步骤的最快方式，无需编写代码。它与 @midscene/ios 共享相同的核心，因此在 Playground 中通过的流程，在脚本中运行会保持一致。

      1. 启动 Playground CLI：
      npx --yes @midscene/ios-playground
      1. 点击窗口中的齿轮按钮进入配置页，粘贴你的 API Key 配置。如果还没有 API Key，请回到 模型配置 获取。

      开始体验

      配置完成后，你可以立即开始体验 Midscene。它提供了多个关键操作 Tab：

      • Act: 与网页进行交互，这就是自动规划（Auto Planning），对应于 aiAct 方法。比如
      在搜索框中输入 Midscene，执行搜索，跳转到第一条结果
      填写完整的注册表单，注意主要让所有字段通过校验
      • Query: 从界面中提取 JSON 结构的数据，对应于 aiQuery 方法。

      类似的方法还有 aiBoolean(), aiNumber(), aiString()，用于直接提取布尔值、数字和字符串。

      提取页面中的用户 ID，返回 { id: string } 结构的 JSON 数据
      • Assert: 理解页面，进行断言，如果不满足则抛出错误，对应于 aiAssert 方法。
      页面上存在一个登录按钮，它的下方有一个用户协议的链接
      • Tap: 在某个元素上点击，这就是即时操作（Instant Action），对应于 aiTap 方法。
      点击登录按钮

      关于自动规划（Auto Planning）和即时操作（Instant Action）的区别，请参考 API 文档。

      集成 Midscene Agent

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

      第 1 步：安装依赖

      npm
      yarn
      pnpm
      bun
      deno
      npm install @midscene/ios dotenv --save-dev

      第 2 步：编写脚本

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

      ./demo.ts
      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();
  })(),
);

      第 3 步：运行示例

      npx tsx demo.ts

      第 4 步：查看报告

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

      API 参考与更多资源

      需要查看构造函数、辅助方法或平台专属设备 API？请移步 iOS API 参考 获取详细参数及自定义操作等高级主题。若想了解跨平台共用的 API，可阅读 通用 API 参考。

      常见问题

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

      请检查以下事项：

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

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

      特性真机模拟器
      端口转发需要 iproxy不需要
      开发者模式必须手动开启默认开启
      UI Automation 设置需手动开启默认开启
      性能真实设备性能取决于 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；否则自动回退到轮询模式。

      更多