web-infra-dev/midscene

Midscene.js – 视觉驱动的 GUI Agent，用于 E2E 测试

它是什么 – 一个 JavaScript 库，允许你用自然语言编写 Web、移动端和桌面应用的全链路（E2E）测试。它使用视觉模型“看”UI，从截图定位元素，执行操作（点击、输入、滚动），并验证用户实际可以看到的内容。

核心思想

• 自然语言测试步骤 – 编写 aiAct、aiWaitFor、aiAssert 调用（或 YAML 用例）来描述用户应该做什么以及应该出现什么。
• 基于视觉的定位 – 无需 CSS 选择器或 DOM 查询；agent 按外观匹配 UI 元素，因此适用于基于画布的控制、仅图标的按钮、跨域 iframe 等。
• 跨平台 API – 相同的 PlaywrightAgent、PuppeteerAgent 或通用 Agent 可用于 Web 浏览器、Android/iOS 设备、HarmonyOS 和远程桌面会话。
• 模型无关且低成本 – 支持多种多模态 LLM（Qwen‑VL、Gemini‑Flash、Doubao‑Seed、UI‑TARS 等），价格可配置；仅截图输入可降低 token 消耗。
• HTML 报告 – 运行后可获得包含截图、元素位置、AI 决策和断言结果的视觉报告，方便调试。

如何使用

1. 创建 Midscene Test 项目（或将 Agent 添加到现有的 Playwright/Puppeteer 测试中）。
2. 配置视觉模型（例如 Qwen3.x 或 gemini‑3.5‑flash）。
3. 编写步骤，可以在 YAML 文件中：

   cases:
     - name: 查找 100 美元以下的耳机
       steps:
         - aiAct: 搜索耳机并将结果过滤为低于 100 美元的价格
         - aiWaitFor: 过滤后的搜索结果可见
         - aiAssert: 搜索结果中有产品，且每个产品的价格低于 100 美元
   

   或者直接在 JavaScript 中：

   await agent.aiAct('搜索耳机并将结果过滤为低于 100 美元的价格');
   await agent.aiWaitFor('过滤后的搜索结果可见');
   await agent.aiAssert('搜索结果中有产品，且每个产品的价格低于 100 美元');
   

4. 运行测试 – Midscene 截取截图，发送给模型，执行操作，并生成交互式 HTML 报告。

支持平台

平台	集成
Web	Playwright、Puppeteer 或 Chrome 桥接模式
Android	ADB 控制的设备/模拟器
iOS	WebDriverAgent 控制的设备/模拟器
HarmonyOS	HDC 控制的设备
桌面（macOS/Windows/Linux）	远程 RDP 或原生键盘/鼠标控制
自定义 UI	提供截图和操作挂钩

基准测试 – 在 AndroidWorld 上报告通过率 93% 以上，MobileWorld 上 78% 以上，AppControlBench 上 96% 以上，整个测试套件模型成本低于 1 美元，展示了准确性和成本效益。

开始使用

• 安装包：npm i @midscene/web（或 Playwright 专用包）。
• 按照网站上的快速入门指南或 Playground Chrome 扩展在没有代码的情况下尝试测试。
• 对于更大的套件，创建 Midscene Test 项目（@midscene/test），并添加自定义 TypeScript 节点以实现可复用的业务逻辑。

社区和生态系统

• 官方文档：https://midscenejs.com
• 示例仓库：https://github.com/web-infra-dev/midscene-example
• 其他语言（Python、Java 等）的 SDK 由社区维护。
• 活跃的 Discord、X 和 Lark 群组提供支持。

为什么重要 – 传统的 UI 测试框架依赖脆弱的选择器和 DOM 知识。Midscene 颠覆了这一点：AI 像人类一样“看”UI，使测试对 UI 变化更具弹性，并能测试仅用代码难以断言的视觉方面（颜色、边框、画布绘制）。

---

Midscene.js 采用 MIT 许可证，欢迎星标和贡献。