#各平台预置 Node

Midscene Test 将可在 YAML 用例与生命周期钩子中调用的每一个能力称为 Node（节点）。

当你在 midscene.config.ts 中通过 createMidsceneNodes({ agentClass, getAgent }) 注册官方 Agent 时，框架会自动注入通用 AI 能力以及对应平台的官方预置 Node。本文汇总各平台开箱即用的预置 Node 列表、参数结构与常见调用方式。

#Node 调用语法速查

YAML 用例支持两种传参方式：

1. 字符串简写：当 Node 声明了 stringInputKey 时，可以直接传入单一字符串：

   steps:
     - gotoUrl: https://bing.com
     - aiAct: 搜索 Midscene 并进入官网
     - aiAssert: 页面标题包含 Midscene
2. 对象传参：当需要配置多个字段或可选参数时，以键值对展开传参；无参数的 Node 传入 {}：

   steps:
     - setViewportSize:
         width: 1440
         height: 900
     - back: {}

#全平台通用 Node

无论测试目标是 Web、移动端（Android、iOS、HarmonyOS）还是桌面端，所有测试工程均支持核心的 AI 操作与断言节点。

#核心 AI 节点

在日常编写测试用例时，最核心且最推荐使用的仅有三个 Node：

cases:
  - name: 搜索商品并验证结果
    steps:
      - aiAct: 在搜索框中输入“马克杯”并点击搜索
      - aiWaitFor: 搜索结果列表加载完成
      - aiAssert: 结果列表中至少展示一款马克杯商品

#其他原子操作与进阶节点

GUI Agent SDK 上的其他原子操作方法（如 aiTap、aiHover、aiInput、aiKeyboardPress、aiScroll、aiDragAndDrop 等）同样可以在 YAML 中直接作为 Node 调用。

不过，出于测试用例的健壮性考虑，不建议在 YAML 中编写过于细致的流程编排：

• 如果将操作拆解为大量的微观点击、聚焦与滚动，不仅会让 YAML 脚本冗长，而且当界面布局发生微调时容易导致用例断裂；
• 通常应优先使用 aiAct 表达用户的业务意图（如“在搜索框输入马克杯并点击搜索”），交由视觉模型自动规划底层的操作步骤。

此外，以下辅助与进阶能力也已注入全局运行时：

• 数据提取与问答：如 aiQuery（结构化数据提取）、aiBoolean / aiString / aiNumber / aiAsk（界面内容提取与问答）。
• 环境指引与报告记录：setAIContext（为后续 AI 操作注入业务规则或通用弹窗处理指引）、recordToReport（向测试报告写入自定义记录或快照）。
• 基础等待与执行：wait（框架级可取消等待，接收 { duration, unit } 参数）、sleep（Agent 级等待）、javascript（执行脚本）。

如果需要在测试中使用这些进阶节点，可以通过 pnpm exec midscene-test nodes 生成的说明书查阅它们完整的输入参数定义。

#Web 专用预置 Node

Web 平台模板基于 Playwright 或 Puppeteer 实现，在通用能力基础上增加了浏览器会话操作：

beforeEach:
  - setViewportSize:
      width: 1280
      height: 800
  - clearCookies: {}
  - gotoUrl: https://todo.example.com

cases:
  - name: 体验待办列表
    steps:
      - aiAct: 在输入框输入“购买牛奶”，按下回车
      - aiAssert: 列表中出现“购买牛奶”

#移动端专用预置 Node

移动端测试依赖设备生命周期与系统级交互按键。Midscene 针对 Android、iOS 与 HarmonyOS 提供了标准化的系统动作与底层通信桥梁。

#Android（@midscene/android）

beforeEach:
  - launch: com.example.shop
  - wait:
      duration: 3
      unit: s

cases:
  - name: 查看商品详情并返回
    steps:
      - aiAct: 点击首页推荐的第一款商品
      - aiAssert: 进入商品详情页，展示立即购买按钮
      - back: {}
      - aiAssert: 回到商城首页

#iOS（@midscene/ios）

beforeEach:
  - launch: com.apple.Preferences

cases:
  - name: 打开系统设置并返回桌面
    steps:
      - aiAssert: 看到设置首页列表
      - home: {}

#HarmonyOS（@midscene/harmony）

beforeEach:
  - launch: com.example.notes

cases:
  - name: 新建一条便签
    steps:
      - aiTap: 右下角新建按钮
      - aiInput:
          prompt: 便签正文输入框
          value: 准备测试数据
      - back: {}
      - aiAssert: 便签列表中展示了“准备测试数据”

#桌面端（Computer）

桌面端（macOS、Windows、Linux）依托全套全平台通用 Node开展自动化测试：

• 通过 aiAct、aiTap、aiDoubleClick、aiRightClick 直接对本地应用窗口、系统菜单栏及对话框进行视觉定位与操作。
• 通过 aiKeyboardPress 输入快捷键（例如聚焦、保存等操作）。
• 当遇到特定复杂的桌面端底层准备逻辑时，可以通过开发自定义 Node补充桌面脚本或系统调用。

#下一步

• 编写 YAML 用例：了解工作流文档结构、变量绑定、标签筛选与生命周期钩子用法。
• 开发自定义 Node：封装业务接口、后端数据准备与团队私有工具。
• 配置测试工程：管理项目配置、环境搭建与多平台工程。