• English

      • Midscene Test overview

      Midscene Test (@midscene/test) is a natural-language E2E testing framework. Describe actions and expectations in YAML, and keep logic that needs precise control in TypeScript. Get started with Midscene Test

      AI and business operations in one YAML file

      Each YAML step calls a Node: an AI, platform, or custom business operation. Compose them into a test case.

      cases/refund.yaml
      beforeEach:  - order.prepare: { status: paid }Business  - gotoUrl: ${shopUrl}/orders/latestBusinesscases:  - name: A paid order supports a full refund    steps:      - aiAct: Apply for a full refund and submitAI      - aiAssert: The page shows that the refund was submittedAI      - order.checkRefund: { status: refunding }BusinessafterEach:  - clearCookies: {}Business

      Test cases maintained by people and AI

      Wrap reusable business logic in custom Nodes. Midscene Test generates a Markdown Node Spec listing every Node and its inputs, so QA engineers and AI agents can write cases without reading TypeScript. Learn how to develop custom Nodes

      1. nodes/order.ts
        defineNode({
  name: 'order.prepare',
  description: "Create a test order",
  inputSchema: z.strictObject({
    status: z.literal('paid'),
  }),
  async execute({ input }) {
    await orders.create(input);
  },
});
      2. midscene-node-spec.md
        ### order.prepare
Create a test order
- status: "paid"
      3. case.yaml
        steps:
  - order.prepare:
      status: paid

      Test framework capabilities

      Midscene Test also includes the capabilities expected of a test framework: lifecycle hooks and cleanup, retries and timeouts, concurrent execution with isolation, and step-level reports.

      Lifecycle hooks and cleanup

      Prepare and clean up resources at the project, file, and case level with setup, fileSetup, beforeAll, beforeEach, and their counterparts. Cleanup still runs after failures, timeouts, or Ctrl+C.

      Project lifecycle

      Retries and timeouts

      Retry failed cases; each attempt reruns beforeEach, steps, and afterEach. Set step timeouts, keep going after a failed step with continue-on-error, and stop early with bail.

      Handling failures

      Concurrency and isolation

      Run YAML files concurrently with maxConcurrentFiles. fileSetup gives each file its own page, Agent, or device, so concurrent files do not share state.

      Concurrency and isolation

      Step-level reports

      The HTML report records screenshots, inputs, outputs, errors, and Agent replay for every step. A #runner-step=last-error link opens the latest failed step from CI notifications or PR comments, and summary.json and result.md are written for scripts and AI agents.

      Output and reports

      Next steps

      Migrating from the legacy YAML runner

      The legacy tasks/flow YAML runner is in maintenance mode, receiving compatibility updates and necessary fixes. Use Midscene Test for new projects and cases. Existing projects can continue using the midscene command; see Migrate to Midscene Test when switching to midscene-test.