Midscene.js：面向端到端测试的 GUI Agent（web-infra-dev/midscene）

项目定位

Midscene.js 的宣传语是“GUI Agent for E2E Testing：AI-powered vision. Cross-platform. Batteries included.”。它把一个视觉驱动的 GUI Agent 与一套测试工具包结合起来，通过相同的 Agent API 覆盖 Web、移动端与桌面应用的 UI 测试编写、验证和调试（配图 1）。

来源给出的 Playwright 示例展示了 Web 测试的基本用法：

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

const agent = new PlaywrightAgent(page);

// Let the Agent carry out a flow, then verify the result.
await agent.aiAct('Search for headphones, then filter the results to under $100');
await agent.aiWaitFor('The filtered search results are displayed');
await agent.aiAssert('Every product in the search results has a price below $100');

运行后打开生成的 HTML 报告，可查看截图、动作与断言结果。模型配置、完整示例与测试运行器集成见 Playwright 指南。

👁️ GUI Agent

Midscene 把 UI 动作和断言建模为人的使用方式：看屏幕、对所见内容执行动作、检查可见结果。用户用自然语言描述任务与预期结果，Midscene 依据截图决定在哪里交互以及界面是否满足预期。

**视觉理解与跨平台动作**

• 像人一样按外观与位置定位元素，然后点击、输入或滚动执行指令。
• 可定位纯图标按钮、自定义控件、<canvas> 以及跨域 iframe 内的元素，无需编写选择器或添加语义标注。
• 同一套 Agent API 适用于 Web、Android、iOS、HarmonyOS 和桌面应用；也可通过提供截图与动作能力接入自定义界面。

**验证用户所见** 断言同样走视觉路径：Midscene 像人类测试者一样检查屏幕，判断预期结果是否可见。用自然语言描述期望外观即可检查颜色、选中高亮、布局和视觉反馈，包括 <canvas> 中绘制的内容或原生应用显示的内容。示例：

await agent.aiAssert('The selected plan has a blue border and a checkmark');
await agent.aiAssert('The error message is visible below the email field');

**基准表现（来源给出的 Benchmark 表）**

• AndroidWorld：Pass@1 93.1%，报告运行使用 Gemini-3.5-Flash
• MobileWorld：Pass@1 78.6%，报告运行使用 Gemini-3.6-Flash
• AppControlBench：Pass@1 96.7%，报告运行使用 Doubao Seed 2.1 Turbo

每份报告都包含运行配置与任务结果；AndroidWorld 报告说明了其环境与 validator 调整。

**成本与模型选择** 基于截图的 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（见 Model Strategy）。

**Showcases（来源列举）**

• Web 自动化：在浏览器中自动注册 GitHub 表单并通过所有字段校验
• iOS 自动化：美团点咖啡
• iOS 自动化：自动点赞 @midscene_ai 的第一条推文
• Android 自动化：DCar 查询小米 SU7 规格
• Android 自动化：预订圣诞酒店
• 机械臂 + 视觉 + 语音用于车载测试

🧰 Testing Kit

“Batteries included”：Midscene 提供把 GUI 自动化变成可维护 E2E 测试项目所需的测试框架、可观测性与集成 API。

**Midscene Test：面向 AI 时代的 E2E 框架** Midscene Test（@midscene/test，Beta）把声明式测试意图与可编程工程分离：用 YAML 编写 UI 流程和期望，用可复用的 TypeScript Nodes 封装 API 调用、数据准备与清理。例如一个退款测试可以通过 API 准备订单、通过 UI 发起退款，并在同一工作流中验证结果。

框架包含项目脚手架、平台预设、生命周期钩子、重试以及执行项目隔离与并发；还会依据已注册 Nodes 及其参数 schema 生成 Markdown 参考，便于人与 AI Agent 发现相同能力并共同维护测试用例（见 Create and extend a project、Write and run tests）。

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

**契合现有技术栈的丰富 API**

这些 Agent API 可通过 Playwright、Puppeteer 或 JavaScript SDK 与既有代码、fixtures 和断言组合，也可以在当前测试框架内采用 Midscene 的视觉能力。AI 编码 Agent 还能通过 Midscene Skills 操作界面。

• aiAct 用于自主流程
• aiTap、aiInput 用于单个动作
• aiAssert 用于断言
• aiQuery 用于结构化数据提取

🚀 上手路径（来源列出的四条）

1. 在 Playground 中试用 Midscene：写脚本前先试验自然语言动作、数据提取与视觉断言；可从 Chrome 扩展开始，或为移动端/桌面端启动 Playground。

1. 用 SDK 或 YAML 编写测试：从 Playwright、Puppeteer 或 Midscene Test 开始。

1. 让 AI agent 操作 UI：安装 Midscene Skills。

1. 在其他平台测试：按 Android、iOS、HarmonyOS 或桌面端指南操作。

📄 资源

• 文档：https://midscenejs.com
• 示例项目：midscene-example
• API 参考：https://midscenejs.com/reference/#common

🤝 社区

Discord、X（关注账号）、Lark Group（飞书交流群）。

🌟 Awesome Midscene（社区扩展项目）

• midscene-ios：为 Midscene 提供 iOS Mirror 自动化支持
• midscene-pc：适用于 Windows、macOS、Linux 的 PC 操作设备
• midscene-pc-docker：预装 Midscene-PC server 的 Docker 镜像
• Midscene-Python：Midscene 自动化的 Python SDK
• midscene-java（@Master-Frank）：Midscene 自动化的 Java SDK
• midscene-java（@alstafeev）：Midscene 自动化的 Java SDK

📝 Credits

项目致谢：Rsbuild 与 Rslib（构建工具）、UI-TARS（开源 agent 模型）、Qwen-VL（开源多模态模型）、scrcpy 与 yume-chan（浏览器端 Android 设备控制）、appium-adb（ADB 的 JavaScript 桥接）、appium-webdriveragent（从 JavaScript 控制 XCTest）、YADB（提升文本输入性能）、libnut-core（跨平台原生键鼠控制）、Puppeteer（浏览器自动化与控制）、Playwright（浏览器自动化、控制与测试）。

📖 引用

如在研究或项目中使用 Midscene.js，来源给出的引用格式为：

@software{Midscene.js,
author = {Xiao Zhou, Tao Yu, YiBing Lin},
title = {Midscene.js: GUI Agent for E2E Testing.},
year = {2025},
publisher = {GitHub},
url = {https://github.com/web-infra-dev/midscene}
}

✨ Star History

页面包含 Star 历史图表（配图 2）：https://api.star-history.com/svg?repos=web-infra-dev/mid

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。