• 简体中文

      • Midscene.js - 面向 E2E 测试的 GUI Agent

      AI 视觉驱动。全平台覆盖。开箱即用。

      Midscene 提供开源 GUI Agent 与 Testing Kit，用于 Web、移动端和桌面应用的 UI 测试与自动化。

      如何使用

      你可以通过同一套 Agent API 操作和验证不同平台的界面。下面以 Playwright 的 Web 测试为例：配置好模型，并在已有的 Playwright page 中打开你的应用后，就可以这样编写测试：

      import { PlaywrightAgent } from '@midscene/web/playwright';

const agent = new PlaywrightAgent(page);

// 让 Agent 完成流程，再验证结果。
await agent.aiAct('搜索耳机，然后将结果筛选为价格低于 100 美元');
await agent.aiWaitFor('筛选后的搜索结果已显示');
await agent.aiAssert('搜索结果中的每件商品价格都低于 100 美元');

      打开生成的 HTML 报告，即可查看截图、操作与断言结果。Playwright 集成指南提供模型配置、完整示例和测试运行器集成步骤。

      GUI Agent

      Midscene 的操作与断言都仿照人使用软件的方式：观察屏幕，根据看到的内容操作，再检查界面呈现的结果。你用自然语言描述任务和预期结果，Midscene 根据截图判断在哪里操作，以及界面是否符合预期。

      视觉理解与跨平台操作

      就像人从屏幕上找到控件一样，Midscene 根据元素的外观和位置进行定位，再通过点击、输入、滚动等操作完成你的指令。无需编写选择器或添加语义化标注，就能定位纯图标按钮、自定义控件、<canvas> 和跨域 iframe 中的元素。

      同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS 和桌面应用。提供截图和操作能力后，你也可以接入自定义界面。

      验证用户真正看到的效果

      断言也采用同样的视觉方式：Midscene 像人工测试时一样观察屏幕，判断预期结果是否呈现。用自然语言描述预期外观，就能检查颜色、选中高亮、布局和视觉反馈，也适用于 <canvas> 绘制的内容和原生应用界面。

      await agent.aiAssert('选中的套餐带有蓝色边框和勾选标记');
await agent.aiAssert('邮箱输入框下方显示了错误提示');

      Benchmark 表现

      Benchmark成绩测试配置完整报告
      AndroidWorldPass@1 93.10%、Pass@2 95.69%、Pass@3 97.41%Midscene 1.9.5、Gemini-3.5-Flash查看报告
      MobileWorldPass@1 78.63%（92/117）Midscene 1.10.3、Gemini-3.6-Flash查看报告
      AppControlBenchPass@1 96.7%（58/60）Midscene 1.12.0、Doubao Seed 2.1 Turbo查看报告

      各报告包含运行配置与任务结果；AndroidWorld 报告还说明了环境与校验器的调整。

      运行成本与模型选择

      基于截图的 UI 操作无需向模型发送庞大的 DOM 树。在上述 AppControlBench 评测中，Midscene 搭配 Doubao Seed 2.1 Turbo 完成了 60 个任务的评测，模型调用总费用为 0.59 美元，其中 58 个任务通过。评测报告提供了逐任务费用与不同模型的对比。

      Midscene 支持 Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、gemini-3.5-flash、UI-TARS 等多模态模型，也包括可自托管的开源选项。你可以先使用单模型，再按场景组合规划模型与视觉模型。在数据提取与页面理解场景中，仍可按需选择携带 DOM。详见模型策略和支持的模型与配置。

      案例展示

      在 Web 浏览器中自主注册 GitHub 表单，并通过所有字段校验：

      更多 iOS、Android、桌面端与自定义界面的实战案例，见 案例展示。

      Testing Kit

      开箱即用：Midscene 提供测试框架、可观测性和集成 API，帮助你将 GUI 自动化组织为可持续维护的 E2E 测试工程。

      Midscene Test：面向 AI 时代的 E2E 测试框架

      Midscene Test（@midscene/test，Beta）将声明式的测试意图与可编程的工程实现分离。用 YAML 编写 UI 流程和预期结果，用可复用的 TypeScript 节点封装 API 调用、数据准备和清理操作。例如，一条退款用例可以先通过 API 准备订单，再通过 UI 申请退款并验证结果。

      框架提供项目脚手架、平台预设、生命周期钩子、重试，以及执行项目之间的隔离与并发。它还会根据已注册的节点及其参数定义生成 Markdown 参考文档，让人和 AI Agent 都能了解可用能力，共同编写和维护用例。详见创建与扩展测试项目和编写与运行用例。

      内置可观测性

      交互式 HTML 报告展示截图、元素定位、AI 决策过程，以及操作和断言结果。Midscene Test 会记录每个 AI 步骤和自定义业务操作的输入、输出、耗时和状态。报告与运行日志为开发者和 AI Agent 提供排查失败所需的上下文。通过 Playground，还可以直接在界面上试验和调整指令。

      丰富的 API，融入现有测试体系

      通过 aiAct 自主执行流程，通过 aiTap、aiInput 控制单步操作，通过 aiAssert 编写断言，通过 aiQuery 提取结构化数据。借助 Playwright、Puppeteer 或 JavaScript SDK，你可以将这些 Agent API 与已有代码、测试夹具和断言组合，在现有测试框架中引入视觉能力。如需了解如何在自主操作与 JavaScript 编排之间选择，请参阅基本概念。AI 编程 Agent 也可以通过 Midscene Skills 操作界面。

      开始使用

      资源与社区

      致谢

      Midscene 构建于众多优秀的开源项目之上，包括 UI-TARS、Qwen、Playwright、Puppeteer、scrcpy、appium、WebDriverAgent、YADB 和 libnut-core。完整列表请见 README。

      License

      Midscene.js 使用 MIT 许可协议。