> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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](/midscene-test/use.md)
## AI and business operations in one YAML file {#ai-and-nodes}
Each YAML step calls a Node: an AI, platform, or custom business operation. Compose them into a test case.

- AI**AI operations**APIs such as aiAct and aiAssert read the screen and follow natural-language instructions.
- Business**Business operations**Custom Nodes use TypeScript to prepare test data, check APIs, and clean up resources.

cases/refund.yaml

````
1beforeEach:2  - order.prepare: { status: paid }Business3  - gotoUrl: ${shopUrl}/orders/latestBusiness45cases:6  - name: A paid order supports a full refund7    steps:8      - aiAct: Apply for a full refund and submitAI9      - aiAssert: The page shows that the refund was submittedAI10      - order.checkRefund: { status: refunding }Business1112afterEach:13  - clearCookies: {}Business
````

## Test cases maintained by people and AI {#nodes-and-spec}
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](/midscene-test/extend.md)

1. nodes/order.ts

```typescript
defineNode({
  name: 'order.prepare',
  description: "Create a test order",
  inputSchema: z.strictObject({
    status: z.literal('paid'),
  }),
  async execute({ input }) {
    await orders.create(input);
  },
});
```

1. midscene-node-spec.md

````markdown
### order.prepare
Create a test order
- status: "paid"
````

1. case.yaml

```yaml
steps:
  - order.prepare:
      status: paid
```

## Test framework capabilities {#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.

[ProjectsetuponTeardown

cases/order.yamlfileSetupbeforeAllafterAll

Case 1beforeEachaiActaiAssertafterEach

Case 2beforeEachaiActaiAssertafterEach

Timeout or Ctrl+CCleanup still runs### 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](/midscene-test/execution#project-lifecycle)[A paid order supports a full refundretry: 1

**Attempt 1**aiAssert timed out after 120 s

afterEach

Retry after cleanup

**Attempt 2**All steps passed

afterEach

testTimeoutcontinue-on-errorbail### 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](/midscene-test/execution#handling-failures)[RunningmaxConcurrentFiles: 3

- `search.yaml`Own page + Agent
- `cart.yaml`Own page + Agent
- `refund.yaml`Own page + Agent

Queued`profile.yaml``orders.yaml`### 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](/midscene-test/execution#concurrency-and-isolation)[report.html#runner-step=last-error

A paid order supports a full refund

1. order.prepare{ status: paid }
1. aiActApply for a full refund and submit
1. aiAssertThe page shows that the refund was submitted
1. order.checkRefundNot run

ScreenshotAgent replay

Error

For scripts and AI agentssummary.jsonresult.md### 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](/midscene-test/running#output-and-exit-codes)

## Next steps
- [Create a test project](/midscene-test/use.md): create, run, change a case, and inspect results.
- [Write YAML cases](/midscene-test/writing.md): author and maintain cases.
- [Built-in Nodes across platforms](/midscene-test/builtin-nodes.md): inspect universal AI capabilities and platform-specific built-in operations.
- [Configure test projects](/midscene-test/configuration.md): manage environment variables, case files, and execution projects.
- [Develop custom Nodes](/midscene-test/extend.md): encapsulate reusable business operations.
- [Run tests](/midscene-test/running.md) and [lifecycle and concurrency](/midscene-test/execution.md): control execution modes, concurrency strategies, and inspect test reports and diagnostics.
- [Run in GitHub Actions](/midscene-test/running.md#run-in-github-actions): connect to CI workflows.
:::info 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](/migrate-to-midscene-test.md) when switching to `midscene-test`.
:::