#Test Runner 概览：自然语言与扩展节点

在 Midscene 的大量实践后，我们认为：在 AI 时代，自动化测试用例的主体应当是自然语言。

用自然语言直接描述测试意图，不仅符合人类的表达习惯，也极具业务表达力。为了让这些自然语言流程既便于人类编写与评审，也便于 AI / Agent 理解与维护，我们选择声明式的 YAML 作为结构载体。

同时，真实项目中的测试流程往往还需要调用外部工具或脚本（如调用业务接口、准备测试数据、管理浏览器资源）。因此，@midscene/test 确立了一套长期演进的测试范式：以自然语言驱动测试主线，以可编程节点（Node）作为扩展能力辅助。

#核心设计：自然语言为主，编程节点为辅

在此范式下，测试框架的设计清晰地划分为两条线：

• 主线（自然语言 + YAML）：承载 80% 以上的业务测试意图。通过声明式 YAML 组装用例，用自然语言描述界面操作（如 `aiAct`）与校验（如 `aiAssert`）。
• 辅线（TypeScript Node）：提供 20% 的可编程扩展能力。使用 TypeScript 注册自定义 Node，负责接口调用、数据准备与资源管理。

面向这套设计，@midscene/test 在平台开发者与用例作者之间建立了清晰的协作平衡点：

• 测试框架维护（平台开发者）：使用 TypeScript 接入浏览器、Agent、外部工具和业务接口，统一管理运行资源和执行生命周期。
• 测试用例维护（用例作者 / Agent）：人类或 Agent 使用 YAML 组合框架提供的能力，直接用自然语言编写和维护测试用例，无需编写 JavaScript 或关注底层实现。

#平滑三方协作：一键导出 Node 说明书

在测试体系中，往往存在三种不同视角的协作角色：编写 TypeScript 节点的框架开发者、编写 YAML 用例的人类作者、以及自动运维测试的 AI Agent。

为了平滑这三方的协作关系，@midscene/test 提供了 describe-nodes 工具，支持一键将所有注册的 Node 定义导出为 Markdown 格式的说明书，让三方协作流畅无阻：

• 框架开发者（高专注）：只需在 TypeScript Node 中声明 Zod 校验规则与描述，文档即可全自动生成，无需耗费额外成本编写和维护 API 手册。
• 用例编写者（无缝查阅）：人类编写者可直接查阅导出的 Markdown，清晰、直观地了解当前项目提供了哪些可用的专属业务节点（如 order.prepare）及参数规则，消除沟通与猜测成本。
• AI 助理（精准调用）：这份 Markdown 说明书具有清晰的类型约束与语义释义，天然是 AI Agent 最完美的上下文知识库。在自动编写、执行和维护 YAML 用例时，Agent 能够直接消化这份说明书，实现精准合规的调用编排。

导出的 Node 说明书示例

例如，一个模拟浏览器地理位置的自定义节点 browser.mockLocation，经 describe-nodes 工具自动导出的 Markdown 说明书结构如下：

## browser.mockLocation

* **标题**：模拟地理位置
* **说明**：伪造浏览器的 GPS 地理位置定位。
* **参数格式 (JSON Schema)**：

{
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "description": "模拟位置的纬度。"
    },
    "longitude": {
      "type": "number",
      "description": "模拟位置的经度。"
    }
  },
  "required": ["latitude", "longitude"]
}

有了这套自动生成的强类型说明书，平台开发、用例编写和 AI 运维得以无缝对接，使后续的实战场景与执行流程流畅无阻。

#实战场景：验证订单退款流程

假设电商团队需要验证已支付订单的退款流程：

1. 编程节点（辅助）：用例开始前调用订单接口或脚本创建测试订单；用例完成后清理测试订单。
2. 自然语言（主线）：Agent 根据 YAML 中的自然语言指令，在页面上提交退款申请并检查结果。

# 1. 编程节点：数据与环境准备
beforeEach:
  - order.prepare:
      status: paid
  - browser.openRefundPage: {}

# 2. 自然语言：业务测试意图
cases:
  - name: 已支付订单可以申请全额退款
    steps:
      - aiAct: 点击申请退款，选择全额退款并提交
      - aiAssert:
          prompt: 页面显示退款申请已提交，退款金额为订单的全部金额
          message: 全额退款申请提交失败

  - name: 已支付订单可以申请部分退款
    steps:
      - aiAct: 点击申请退款，输入退款金额 10 元并提交
      - aiAssert:
          prompt: 页面显示退款申请已提交，退款金额为 10 元
          message: 部分退款申请提交失败

# 3. 编程节点：资源清理
afterEach:
  - order.cleanup: {}

框架维护者注册 order.prepare、browser.openRefundPage 和 order.cleanup 等自定义 Node 负责数据与页面管理，Midscene Node 负责界面操作与校验。测试意图与技术实现彼此分离，两类维护工作可以独立演进。

#接下来

• 阅读 扩展和维护 Test Runner，了解如何注册 Node、管理运行资源和配置 Test Project。
• 阅读 编写和运行测试用例，了解 Case、Step、生命周期和运行结果。