#迁移到 Midscene Test

旧版 YAML 与原生 Midscene Test 共用底层执行内核和报告页面，但用户入口相互独立。midscene 负责旧版 tasks/flow 文件、YAML 批配置和旧 CLI 参数；midscene-test 负责原生 cases/steps 文件、TypeScript 或 JavaScript 项目配置、生命周期和 Node。

本文把迁移分为两条路径：

• 原地升级：旧用例、批配置、目录结构和 midscene 命令均保持不变，先获得共享执行内核和新报告，不改变输入契约。
• 原生迁移：按完整文件把旧字段改写为 Test 的文档、Case 和 Step，用项目配置替换 YAML 批配置，再把这些文件切换到 midscene-test。

旧版字段的完整参考仍保留在 YAML 脚本运行器和 YAML 格式的工作流中，供现有项目维护和迁移时查阅。

#路径一：原地升级旧链路

如果项目已经安装 @midscene/cli，升级后继续使用原命令。midscene 会保留旧输入语义，通过共享内核执行，并生成新的报告页面：

pnpm exec midscene ./flow.yaml
pnpm exec midscene --config ./batch.yaml

原来的平台配置、agent、环境变量插值、task continuation、整文件重试、输出文件和 summary 仍按旧语义处理；报告切换为新 Test 页面，旧 HTML 文件无需转换，重新运行即可生成。旧 agent.generateReport: false 仍生效。

旧 --files、--setup、--concurrent、--retry、--continue-on-error、--summary、--headed、--keep-window、--share-browser-context、--dotenv-override、--dotenv-debug、--<target>.<field> 和 --no-<target>.<field> 继续由 midscene 接受。它们不是 midscene-test 参数，也不出现在 Test 主帮助中。

#路径二：迁移为原生 Test 项目

建议按下面的顺序迁移，保证每一步都可以独立运行和对比结果：

1. 先使用 midscene 运行原项目，保存退出状态、summary 和新报告作为基线。
2. 使用 pnpm dlx @midscene/test create 创建对应平台的 Test 项目，从生成的 midscene.config.ts 和 setup 开始配置运行环境。
3. 将旧批配置映射到执行项目：共享资源放入 setup，每份文件独立使用的页面、设备和 Agent 放入 fileSetup；业务前置步骤放入 YAML 的 beforeAll 或 beforeEach。
4. 每次完整地把一个 tasks/flow 文件改为 cases/steps，移入原生文件选择范围，再用 midscene-test 运行；未转换文件继续交给 midscene。
5. 运行 pnpm exec midscene-test nodes --project <name> 生成当前项目的 Node 说明书，根据说明书校验动作名称、参数和字符串简写。
6. 全部转换后，移除旧批配置、旧命令和旧链路专用参数。

#用例结构映射

旧版：

web:
  url: https://example.com

tasks:
  - name: 搜索商品
    continueOnError: true
    flow:
      - ai: 搜索马克杯
      - aiAssert: 搜索结果中包含马克杯
        errorMessage: 未找到目标商品

原生 Test：

beforeEach:
  - gotoUrl: https://example.com

cases:
  - name: 搜索商品
    steps:
      - aiAct: 搜索马克杯
      - aiAssert:
          prompt: 搜索结果中包含马克杯
          message: 未找到目标商品

保留旧文件即可保留旧失败策略；手写原生 Case 则采用原生语义，不保证调度行为一一等价。Step 的 $: { continue-on-error: true } 只让同阶段后续 Step 继续，不控制旧 task 之间的调度，也不会把失败 Case 改为成功。

#flow 动作映射

旧 runtime 会继续接受左侧字段，并在内部适配到共享内核；这种内部转换不是原生 Test 的输入契约。迁移文件时应改写为右侧的原生形式，并以 midscene-node-spec.md 中当前项目实际注册的 Node 为准。

#具体示例：迁移一个提交订单 Case

下面的旧用例填写收货人、等待提交按钮可用、提交订单并记录结果。它同时使用了 task 失败策略、动作别名、定位输入、动作超时、断言错误消息、固定等待和报告记录：

web:
  url: https://shop.example.com/checkout

tasks:
  - name: 提交订单
    continueOnError: true
    flow:
      - aiInput: Alice
        locate: 收货人姓名输入框
      - aiWaitFor: 提交订单按钮已启用
        timeout: 10000
      - ai: 点击提交订单按钮
      - aiAssert: 页面显示订单提交成功
        errorMessage: 提交后没有出现成功提示
      - sleep: 500
      - recordToReport: 订单提交结果
        content: 已完成下单流程

迁移成原生 Test 后，同一个 Case 可以写成：

beforeEach:
  - gotoUrl: https://shop.example.com/checkout

cases:
  - name: 提交订单
    steps:
      - aiInput:
          prompt: 收货人姓名输入框
          value: Alice
      - aiWaitFor:
          prompt: 提交订单按钮已启用
          options:
            timeoutMs: 10000
      - aiAct: 点击提交订单按钮
      - aiAssert:
          prompt: 页面显示订单提交成功
          message: 提交后没有出现成功提示
      - wait:
          duration: 500
          unit: ms
      - recordToReport:
          title: 订单提交结果
          options:
            content: 已完成下单流程

这里发生了几类转换：

1. web.url 不再和用例内容混在一起。浏览器和页面由项目配置中的准备函数创建，需要在每个 Case 开始时进入结算页，因此 URL 放到 beforeEach 的 gotoUrl。
2. task 变成 Case；原生 Test 默认在 Case 失败后继续，因此这个例子无需额外的继续参数。
3. aiInput 的值和定位描述从同级旧字段拆成 Node 的 value 与 prompt。
4. aiWaitFor.timeout 是动作自身的等待上限，所以放入 options.timeoutMs。如果要限制整个 Step，应另用 $: { timeout: 10000 }。
5. ai 统一为 aiAct，aiAssert.errorMessage 改为 aiAssert.message。
6. 固定等待改用原生通用 wait Node；报告标题与正文分别放入 recordToReport.title 和 options.content。

这个例子只调整输入结构，没有改变业务执行顺序。实际迁移时应先运行 pnpm exec midscene-test nodes --project <name>，生成当前项目的 midscene-node-spec.<project-name>.md。以这份 Node 说明书为准确认 gotoUrl、aiInput、aiWaitFor 等 Node 是否可用以及参数如何填写，不要根据其他平台的示例推测。

#脚本和 Agent 配置映射

midscene 会继续读取旧 YAML 顶层配置。迁移为原生 Test 时，这些字段不再放在 Case YAML 中，而是进入 midscene.config.ts、setup / fileSetup 或 Node。共享资源放入 setup，每份文件独立使用的资源放入 fileSetup，业务前置步骤放入 YAML 钩子。三者的区别见setup、fileSetup 与 beforeAll。

准备函数的完整写法和各平台 Node 注册方式见配置运行环境。

#批配置映射

旧版 batch.yaml：

files:
  - flows/cases/**/*.yaml
setup: flows/setup.yaml
concurrent: 2
retry: 1
continueOnError: false
summary: result.json
headed: true

原生 Test 把执行参数放在 midscene.config.ts：

import { defineTestProject } from '@midscene/test/config';
import { nodes, setup } from './test-runtime';

export default defineTestProject({
  nodes,
  projects: [
    {
      name: 'default',
      setup,
      files: {
        include: ['flows/cases/**/*.yaml'],
      },
      retry: 1,
    },
  ],
  test: {
    bail: 1,
  },
  output: {
    reportDir: './midscene_run/report',
  },
});

上面的原生示例迁移了文件选择、用例重试和失败阈值，未保留旧版的前置文件和文件并发。需要并发时，按文件并发配置补充 test.maxConcurrentFiles 和 fileSetup。保留原用例和批配置时，继续使用 midscene；旧 concurrent / --concurrent 和前置文件行为不变。

midscene 保留旧输出命名规则：显式 flow name、未命名提取结果的数字键，以及重复名称的覆盖规则均保留。

#验证迁移结果

同一个用例先用 midscene 运行旧版本，再用 midscene-test 运行转换后的版本，至少核对：

• 进程退出码和失败后是否继续执行。
• 重试单位是 Case 还是整个文件。
• 环境变量、平台连接参数和初始页面状态。
• AI 动作输入、超时和断言失败信息。
• 业务输出的消费方式，以及新 Test 报告中的 Step 结果。
• 并发执行时页面、Agent、设备和测试数据是否隔离。
• 失败、超时和 Ctrl+C 中断后，生命周期钩子与资源清理是否完成。

迁移完成后，新增用例应使用 cases/steps。只有尚未迁移的文件继续保留 tasks/flow，避免在新代码中继续扩大兼容格式的使用范围。