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

# Midscene Test 概览

Midscene Test（`@midscene/test`）是面向自然语言的 E2E 测试框架。用 YAML 描述操作和预期，需要精确控制的逻辑交给 TypeScript。[开始使用 Midscene Test](/zh/midscene-test/use.md)
## AI 操作与业务操作写在同一个 YAML 里 {#ai-and-nodes}
YAML 中的每个步骤都调用一个 Node，可以是 AI 操作、平台操作或自定义业务操作；把这些步骤组合起来，就构成一个测试用例。

- AI**AI 操作**aiAct、aiAssert 等接口读取界面截图，按自然语言指令操作和断言。
- 业务**业务操作**在自定义 Node 中用 TypeScript 准备测试数据、校验接口并清理资源。

cases/refund.yaml

````
1beforeEach:2  - order.prepare: { status: paid }业务3  - gotoUrl: ${shopUrl}/orders/latest业务45cases:6  - name: 已支付订单支持全额退款7    steps:8      - aiAct: 申请全额退款并提交AI9      - aiAssert: 页面显示退款申请已提交AI10      - order.checkRefund: { status: refunding }业务1112afterEach:13  - clearCookies: {}业务
````

## 让人和 AI 共同维护测试用例 {#nodes-and-spec}
把可复用的业务逻辑封装成自定义 Node。Midscene Test 会生成 Markdown 格式的 Node 说明书（Node Spec），列出每个 Node 及其参数，测试工程师和 AI Agent 无需阅读 Node 的 TypeScript 实现就能编写用例。[了解如何开发自定义 Node](/zh/midscene-test/extend.md)

1. nodes/order.ts

```typescript
defineNode({
  name: 'order.prepare',
  description: "创建测试订单",
  inputSchema: z.strictObject({
    status: z.literal('paid'),
  }),
  async execute({ input }) {
    await orders.create(input);
  },
});
```

1. midscene-node-spec.md

````markdown
### order.prepare
创建测试订单
- status: "paid"
````

1. case.yaml

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

## 测试框架能力 {#framework-capabilities}
Midscene Test 也具备测试框架应有的工程能力：生命周期钩子与资源清理、失败重试与超时、相互隔离的并发执行，以及精确到步骤的报告。

[项目setuponTeardown

cases/order.yamlfileSetupbeforeAllafterAll

Case 1beforeEachaiActaiAssertafterEach

Case 2beforeEachaiActaiAssertafterEach

超时或 Ctrl+C清理照常执行### 生命周期钩子与资源清理

通过 setup、fileSetup、beforeAll、beforeEach 及对应的清理钩子，分别在项目、文件和用例层级准备与清理资源。用例失败、超时或按下 Ctrl+C 后，清理流程仍会执行。

项目生命周期](/zh/midscene-test/execution#项目生命周期)[已支付订单支持全额退款retry: 1

**第 1 次尝试**aiAssert 超时（120 秒）

afterEach

清理完成后重试

**第 2 次尝试**全部步骤通过

afterEach

testTimeoutcontinue-on-errorbail### 失败重试与超时

失败用例可以重试，每次尝试都会重新执行 beforeEach、步骤和 afterEach。可以设置步骤超时，用 continue-on-error 在步骤失败后继续执行，用 bail 提前停止。

失败时如何执行](/zh/midscene-test/execution#失败时如何执行)[运行中maxConcurrentFiles: 3

- `search.yaml`独立页面与 Agent
- `cart.yaml`独立页面与 Agent
- `refund.yaml`独立页面与 Agent

排队中`profile.yaml``orders.yaml`### 并发与隔离

通过 maxConcurrentFiles 并发运行多个 YAML 文件。fileSetup 为每个文件准备独立的页面、Agent 或设备，并发文件之间不共享状态。

并发与资源隔离](/zh/midscene-test/execution#并发与资源隔离)[report.html#runner-step=last-error

已支付订单支持全额退款

1. order.prepare{ status: paid }
1. aiAct申请全额退款并提交
1. aiAssert页面显示退款申请已提交
1. order.checkRefund未执行

截图Agent 回放

错误

供脚本和 AI Agent 读取summary.jsonresult.md### 精确到步骤的报告

HTML 报告记录每个步骤的截图、输入、输出、错误和 Agent 回放。通过 #runner-step=last-error 链接，可以从 CI 通知或 PR 评论直接打开最近一次失败的步骤；summary.json 和 result.md 则供脚本和 AI Agent 读取。

输出与报告](/zh/midscene-test/running#输出与退出码)

## 下一步
- [创建测试项目](/zh/midscene-test/use.md)：首次创建、运行、修改用例并查看结果。
- [编写 YAML 用例](/zh/midscene-test/writing.md)：日常编写与维护用例。
- [各平台预置 Node](/zh/midscene-test/builtin-nodes.md)：查阅通用 AI 能力与各平台预置操作。
- [配置测试工程](/zh/midscene-test/configuration.md)：管理环境变量、用例文件和执行项目。
- [开发自定义 Node](/zh/midscene-test/extend.md)：封装可复用的业务操作。
- [运行测试](/zh/midscene-test/running.md)与[生命周期与并发](/zh/midscene-test/execution.md)：控制执行方式、并发策略，并获取测试报告与诊断结果。
- [在 GitHub Actions 中运行](/zh/midscene-test/running.md#在-github-actions-中运行)：接入 CI 流程。
:::info 从旧版 YAML 运行器迁移
旧版 `tasks/flow` YAML 运行器已进入维护状态，仅保留兼容更新和必要修复。新项目和新增用例推荐使用 Midscene Test。已有项目可以继续使用 `midscene` 命令；如需迁移到 `midscene-test`，请参阅[迁移到 Midscene Test](/zh/migrate-to-midscene-test.md)。
:::