#Migrate to Midscene Test

Legacy YAML and native Midscene Test share the same underlying execution kernel and report page, but they have separate user-facing entries. The midscene command owns legacy tasks/flow files, YAML batch configuration, and legacy CLI options. The midscene-test command owns native cases/steps files, TypeScript or JavaScript project configuration, lifecycle hooks, and Nodes.

There are two migration paths:

• Upgrade in place: keep legacy cases, batch configuration, directory layout, and the midscene command unchanged. This adopts the shared execution kernel and new report without changing the input contract.
• Native migration: rewrite complete files as Test Documents, Cases, and Steps; replace batch YAML with project configuration; then switch those files to midscene-test.

The complete legacy field reference remains available in YAML script runner and Workflow in YAML format for maintaining and migrating existing projects.

#Path 1: upgrade legacy execution in place

If the project already uses @midscene/cli, upgrade it and keep the existing command. midscene preserves the legacy input contract while executing through the shared kernel and generating the new report page:

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

Platform configuration, agent, environment interpolation, task continuation, whole-file retries, output files, and summary retain their legacy semantics. Reports use the new Test page; existing HTML files need no conversion, so rerun to regenerate them. Legacy agent.generateReport: false remains respected.

Legacy flags such as --files, --setup, --concurrent, --retry, --continue-on-error, --summary, --headed, --keep-window, --share-browser-context, --dotenv-override, --dotenv-debug, --<target>.<field>, and --no-<target>.<field> remain accepted by midscene. They are not midscene-test options and do not appear in its help.

#Path 2: migrate to a native Test project

Use the following order so each step can be run and compared independently:

1. Run the existing project with midscene and save its exit status, summary, and new report as a baseline.
2. Use pnpm dlx @midscene/test create to create a Test project for the target platform. Start with the generated midscene.config.ts and setup.
3. Map the legacy batch configuration to an Execution Project: put shared resources in setup, per-file pages, devices, and Agents in fileSetup, and business prerequisites in YAML beforeAll or beforeEach.
4. Convert one complete tasks/flow file to cases/steps, move it into the native file selection, and run it with midscene-test. Keep unconverted files on midscene.
5. Run pnpm exec midscene-test nodes --project <name> to generate the current Project's Node Spec, then validate action names, inputs, and string shorthand against it.
6. After all files are converted, remove the legacy batch configuration, legacy command, and legacy-only command-line options.

#Case structure mapping

Legacy YAML:

web:
  url: https://example.com

tasks:
  - name: Search for a product
    continueOnError: true
    flow:
      - ai: Search for a mug
      - aiAssert: The results contain a mug
        errorMessage: The expected product was not found

Native Test:

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

cases:
  - name: Search for a product
    steps:
      - aiAct: Search for a mug
      - aiAssert:
          prompt: The results contain a mug
          message: The expected product was not found

Keeping old files unchanged preserves their failure policy. Rewriting them as native Cases adopts native semantics; it is not an exact scheduling equivalence. Step $: { continue-on-error: true } continues later Steps in that phase, not later legacy tasks, and does not make a failed Case pass.

#Flow action mapping

The legacy runtime keeps accepting the fields in the left column and adapts them internally to the shared kernel. That internal adaptation is not a native Test input contract. When migrating a file, write the native form in the right column and use the Nodes registered in the project's midscene-node-spec.md as the source of truth.

#Concrete example: migrate one order-submission Case

The following legacy case fills in a recipient, waits for the submit button, submits the order, and records the result. It uses task failure policy, an action alias, locate input, action timeout, an assertion message, a fixed wait, and report recording:

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

tasks:
  - name: Submit an order
    continueOnError: true
    flow:
      - aiInput: Alice
        locate: Recipient name input
      - aiWaitFor: The submit order button is enabled
        timeout: 10000
      - ai: Click the submit order button
      - aiAssert: The page shows that the order was submitted
        errorMessage: No success message appeared after submission
      - sleep: 500
      - recordToReport: Order submission result
        content: The checkout flow completed

The same Case in native Test YAML is:

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

cases:
  - name: Submit an order
    steps:
      - aiInput:
          prompt: Recipient name input
          value: Alice
      - aiWaitFor:
          prompt: The submit order button is enabled
          options:
            timeoutMs: 10000
      - aiAct: Click the submit order button
      - aiAssert:
          prompt: The page shows that the order was submitted
          message: No success message appeared after submission
      - wait:
          duration: 500
          unit: ms
      - recordToReport:
          title: Order submission result
          options:
            content: The checkout flow completed

The conversion has several parts:

1. web.url no longer sits beside case content. Preparation functions in the project configuration create the browser and page. Because every Case must start on the checkout page, gotoUrl in beforeEach owns the URL.
2. The task becomes a Case. Native Test already continues after a failed Case, so this example needs no continuation option.
3. The aiInput value and locate description move from legacy sibling fields to the Node's value and prompt.
4. aiWaitFor.timeout limits that wait operation, so it becomes options.timeoutMs. To limit the complete Step instead, use $: { timeout: 10000 }.
5. ai becomes aiAct, and aiAssert.errorMessage becomes aiAssert.message.
6. The fixed delay uses the native common wait Node. The report title and body move to recordToReport.title and options.content.

This example changes the input structure without changing business execution order. During a real migration, run pnpm exec midscene-test nodes --project <name> to generate the current Project's midscene-node-spec.<project-name>.md. Use this Node Spec—not examples from another platform—to confirm whether gotoUrl, aiInput, aiWaitFor, and the other referenced Nodes are available and how to provide their inputs.

#Script and Agent configuration mapping

midscene continues to read top-level legacy YAML configuration. In a native migration, move these fields out of Case YAML and into midscene.config.ts, setup / fileSetup, or Nodes. Use setup for shared resources, fileSetup for each file's resources, and YAML hooks for business prerequisites. See setup, fileSetup, and beforeAll.

See Configure the runtime environment for complete preparation and platform Node registration examples.

#Batch configuration mapping

Legacy batch.yaml:

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

Native Test moves execution settings into 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',
  },
});

The native example above migrates file selection, case retries, and the failure threshold; it does not preserve legacy setup-file behavior or file concurrency. For concurrency, add test.maxConcurrentFiles and fileSetup as shown in File concurrency. To keep existing cases and batch configuration, continue using midscene; legacy concurrent / --concurrent and setup-file behavior remain unchanged.

The midscene entry preserves legacy output naming: explicit flow name values, numeric keys for unnamed extracted results, and the existing overwrite behavior for duplicate names.

#Validate the migration

Run the legacy version with midscene and the converted version with midscene-test, then compare at least:

• Process exit status and continuation after a failure.
• Whether retries apply to one Case or the complete file.
• Environment variables, platform connection settings, and initial page state.
• AI action inputs, timeouts, and assertion failure messages.
• Business output consumers and Step results in the new Test report.
• Page, Agent, device, and test-data isolation during concurrent execution.
• Lifecycle hooks and resource cleanup after failures, timeouts, and Ctrl+C interruption.

After migration, write new cases with cases/steps. Keep tasks/flow only in files that have not yet been migrated so the compatibility format does not expand into new code.