#iOS 开始使用

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

#配置 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 服务。

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

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

#验证环境配置

配置完成后，可以通过访问 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

2. 点击窗口中的齿轮按钮进入配置页，粘贴你的 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 install @midscene/ios --save-dev

yarn add @midscene/ios --save-dev

pnpm add @midscene/ios --save-dev

bun add @midscene/ios --save-dev

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

#第 2 步：编写脚本

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

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。

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

#如何自定义 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

#更多

• 查看所有 Agent 方法：API 参考（通用）
• iOS 专属参数与接口：iOS Agent API
• 示例项目
  • 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