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

# 像人一样看懂界面
用自然语言完成 E2E 测试

Midscene.js 提供基于视觉的 GUI Agent 和自然语言 E2E 测试框架，支持 Web、移动端和桌面应用。

**15k+**Github Stars

[**MIT**完全开源](https://github.com/web-infra-dev/midscene/blob/main/LICENSE)

**#2**Github 趋势榜第2名

## 用自然语言描述步骤与预期 {#test-intent}
按用户的操作意图写步骤，按用户看到的结果写预期。同一个测试意图，可以用 YAML 表达，也可以接入现有 JavaScript 测试。

**YAML · @midscene/test**

```yaml
beforeEach:
  - gotoUrl: https://your-shop.example

cases:
  - name: "筛选 100 美元以下的耳机"
    steps:
      - aiAct: "搜索耳机，然后将结果筛选为价格低于 100 美元"
      - aiWaitFor: "筛选后的搜索结果已显示"
      - aiAssert: "搜索结果中有商品，且每件商品价格都低于 100 美元"
```

**Rstest + JavaScript**

```javascript
import { test } from '@rstest/core';
import { PlaywrightAgent } from '@midscene/web/playwright';

// 省略模型配置、page 初始化与资源清理
test("筛选 100 美元以下的耳机", async () => {
  const agent = new PlaywrightAgent(page);
  await agent.aiAct("搜索耳机，然后将结果筛选为价格低于 100 美元");
  await agent.aiWaitFor("筛选后的搜索结果已显示");
  await agent.aiAssert("搜索结果中有商品，且每件商品价格都低于 100 美元");
}, 180_000);
```

**Vitest + JavaScript**

```javascript
import { test } from 'vitest';
import { PlaywrightAgent } from '@midscene/web/playwright';

// 省略模型配置、page 初始化与资源清理
test("筛选 100 美元以下的耳机", async () => {
  const agent = new PlaywrightAgent(page);
  await agent.aiAct("搜索耳机，然后将结果筛选为价格低于 100 美元");
  await agent.aiWaitFor("筛选后的搜索结果已显示");
  await agent.aiAssert("搜索结果中有商品，且每件商品价格都低于 100 美元");
}, 180_000);
```

![](/images/backgrounds/section-divider-light.svg)![](/images/backgrounds/section-divider-dark.svg)

## 为测试而生的 GUI Agent {#gui-agent}
Midscene 的 GUI Agent 为已有的 JavaScript 测试提供视觉操作与断言能力。Web 场景推荐接入 [Playwright Test](/zh/integrate-with-playwright.md)，移动端和桌面端推荐接入 [Rstest](/zh/sdk/rstest.md) 或 [Vitest](/zh/sdk/vitest.md)。
### 像人一样观察、操作并验证结果 {#visual-capabilities}
E2E 测试的初衷是从用户视角验证完整流程，所以 Midscene 按用户的方式来测。

1. **观察屏幕**读取截图，不依赖 DOM
1. **执行操作**找到目标，点击、输入或滚动
1. **检查结果**断言用户实际看到的内容

[查看实际案例](/zh/showcases)

### 一套 API，覆盖不同平台 {#platforms}
视觉定位不依赖界面渲染结构，同一套 API 可用于 Web、移动端、桌面端以及 canvas 等自定义界面。

[**Web**`@midscene/web`](/zh/integrate-with-playwright)[**Android**`@midscene/android`](/zh/platforms/android)[**iOS**`@midscene/ios`](/zh/platforms/ios)

同一套 API`await agent.**aiAct**('搜索耳机')`

[**HarmonyOS**`@midscene/harmony`](/zh/platforms/harmonyos)[**桌面**`@midscene/computer`](/zh/platforms/desktop)[**自定义界面**`@midscene/core`](/zh/integrate-with-any-interface)

### 模型选择与成本 {#model-options}

[![](/images/models/supported-models-light.svg)![](/images/models/supported-models-dark.svg)### 支持多种模型

支持豆包、DeepSeek、Qwen、GPT、Gemini、Kimi 等模型，按效果与预算选择。

查看模型配置](/zh/model-selection)[评测案例 · AppControlBench

**$0.59**/ 60 项任务

模型调用总费用### 低模型调用成本

以豆包 Seed 2.1 Turbo 为例：该次 AppControlBench 评测中，60 项任务通过 58 项，模型调用总费用为 $0.59。

查看评测报告](/zh/app-control-bench-report)

### Benchmark 成绩 {#benchmarks}
- **AndroidWorld**：Pass\@1 为 93.1%，Pass\@3 为 97.4%。[查看评测报告](/zh/android-world-benchmark-report.md)
- **MobileWorld**：Pass\@1 为 78.6%，完成 117 项任务中的 92 项。[查看评测报告](/zh/mobile-world-benchmark-report.md)
- **AppControlBench**：Pass\@1 为 96.7%，通过 60 项任务中的 58 项。[查看评测报告](/zh/app-control-bench-report.md)
## 全新设计的自然语言 E2E 测试框架 {#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 无需阅读 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#输出与退出码)

## 谁在使用 Midscene {#users}

[![](/images/icons/bytedance-color.svg)ByteDance](https://www.bytedance.com)[![](/images/users/alibaba-color.svg)阿里巴巴](https://www.alibaba.com)[![](/images/users/ctrip-color.svg)携程](https://www.ctrip.com)[![AVATR](/images/users/avatr-wordmark.svg)](https://www.avatr.com)[![](/images/users/xiaomi-color.svg)小米](https://www.mi.com)[![爱奇艺](/images/users/iqiyi-color.svg)](https://www.iqiyi.com)[![哔哩哔哩](/images/users/bilibili-zh-color.svg)](https://www.bilibili.com)[![Autel](/images/users/autel-color.svg)](https://autelenergy.com)[![](/images/users/rome-os.svg)Rome OS](https://github.com/rome-os/rome)[![](/images/users/volcengine.png)火山引擎](https://www.volcengine.com)[![](/images/users/douyin-color.svg)抖音](https://www.douyin.com)[![](/images/users/tiktok-color.svg)TikTok](https://www.tiktok.com)[![](/images/users/lark-color.svg)飞书](https://www.larksuite.com)[![](/images/users/soda-music-color.svg)汽水音乐](https://www.douyin.com/qishui)[![](/images/users/doubao-color.png)豆包](https://www.doubao.com)[![懂车帝](/images/users/dongchedi-color.svg)](https://www.dongchedi.com)

## 下一步 {#next-steps}
- **了解基本概念**：阅读[基础概念](/zh/basics.md)，了解 GUI Agent 的工作方式与核心能力
- **开始使用**：在[开始使用](/zh/get-started.md)中回答几个问题，完成第一次运行
- **创建测试工程**：用 [Midscene Test](/zh/midscene-test/use.md) 编写并运行 YAML 用例
- **通过代码编写测试**：Web 场景接入 [Playwright Test](/zh/integrate-with-playwright.md)，移动端和桌面端接入 [Rstest](/zh/sdk/rstest.md) 或 [Vitest](/zh/sdk/vitest.md)
- **执行独立自动化流程**：使用 [JavaScript SDK 编写脚本](/zh/sdk/standalone.md)
如果希望让 AI 编程 Agent 操作界面，可以了解 [Midscene Skills](/zh/skills.md)。