Midscene.js：基于视觉大模型的跨端 UI 自动化测试框架-编程实验室

Midscene.js：基于视觉大模型的跨端 UI 自动化测试框架

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

Midscene.js 是面向 E2E 测试的GUI Agent框架：它不解析 DOM，而是通过视觉大模型读取界面截图，用自然语言完成点击、输入等 UI 自动化操作，并提供断言、数据提取与可交互 HTML 报告。同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS 与桌面应用，适合把 UI 回归测试从选择器维护中解耦，或接入现有 Playwright 测试流水线。

快速跑通

最短路径是把 Midscene 挂到已有的 Playwright 页面上，三步以内跑起来：

安装依赖并配置模型。模型用环境变量指定，指向任一多模态模型服务即可：

npm i @midscene/web playwright

在已有的 Playwrightpage上创建 Agent，执行一条流程：

import { PlaywrightAgent } from '@midscene/web/playwright'; const agent = new PlaywrightAgent(page); await agent.aiAct('搜索耳机，并把结果过滤到 100 美元以下'); await agent.aiWaitFor('过滤后的搜索结果已展示'); await agent.aiAssert('搜索结果中每件商品的价格都低于 100 美元');

预期输出：aiAct把自然语言流程拆成具体动作自动执行，aiWaitFor等待界面状态出现，aiAssert在断言不成立时抛出错误。以MIDSCENE_REPORT=true运行时会在本地生成 HTML 报告，浏览器打开即可逐步查看截图、动作序列与断言结果。

能力边界

能做

以截图外观与位置定位元素，不依赖选择器：纯图标按钮、canvas 绘制区域、跨域 iframe 内部元素都能直接操作。
同一套 Agent API（aiAct、aiTap、aiInput、aiQuery、aiAssert）覆盖 Web、Android、iOS、HarmonyOS 与桌面端，跨端迁移只换设备对象。
自然语言断言与结构化数据提取：aiAssert校验视觉呈现，aiQuery按 schema 提取页面信息。
可作为 Playwright / Puppeteer 的补充层接入现有测试框架，也支持用 YAML 编写用例。

暂时做不好

每一步都经过视觉模型推理，单步延迟和 API 成本无法消除；离线场景只能自托管开源模型，效果通常弱于云端旗舰模型。
非结构化界面（低分辨率远程画面、复杂 Canvas 游戏、频繁变化的动态广告位）识别准确率下降，需要配合等待与重试。
视觉断言只覆盖屏幕上可见的部分，接口与后端状态的正确性仍要靠传统断言兜底。
超长流程一次给完容易漂移，拆成多个短aiAct更稳定。

典型工作流

前端重构后的 UI 回归。背景：电商搜索、筛选、加购等流程每次发版都要回归，选择器脚本随重构频繁失效。思路：用aiAct以自然语言描述完整购物流程，断言点写成"价格区间、选中态高亮"这类视觉预期，挂到现有 Playwright fixture 上；失败时打开 HTML 报告核对 AI 每一步看到的截图，判断是识别问题还是真实缺陷。验证点：一次 UI 调整后，修改一条指令即可恢复，不需要批量修选择器。

桌面与远程屏幕操作。背景：部分桌面应用或 RDP 远程会话没有可访问的 DOM，传统工具只能录制坐标，维护困难。思路：走桌面平台适配层，以屏幕截图为唯一输入，把"打开设置、切换开关"等操作写成自然语言指令；敏感操作保留人工确认环节。验证点：远程画面上操作可闭环完成，报告中每一步截图可复核。

跨端一致性验证。背景：同一业务流程在 Web 与 Android 上分别实现，需要确认视觉与数据表现一致。思路：同一组指令分别在PlaywrightAgent与AndroidAgent上执行，用aiQuery按同一 schema 提取关键数据做比对；端上差异（输入法、安全页面、截图策略）作为显式失败项记录。验证点：两端提取的数据一致，差异能被报告定位到具体步骤。

内部协作机制

核心推理循环位于 packages/core/src/agent/：Agent 截图后交给视觉模型做规划，把规划结果映射为点击、输入等动作，再对执行结果做断言，循环直至流程完成；报告生成与元素缓存也挂在这一层。各平台适配层只负责提供"截图 + 执行动作"两类能力，例如 packages/web-integration/src/ 基于 Playwright / Puppeteer 页面对象实现该契约，Android、iOS 与桌面包则分别以 adb、WDA、系统输入通道实现同样的接口。平台层不感知模型细节，core 层也不感知平台差异，新端接入只需补齐截图与动作能力。

生产落地要点

稳定性兜底：在aiAssert/aiWaitFor外层加有限次重试；对加载中的页面先用aiWaitFor等待目标状态再执行断言，避免把渲染未完成误判为失败。
模型选型：从一个模型起步；对成本或数据出境敏感的项目自托管开源多模态模型，精度要求高的关键步骤再考虑更强模型，按步骤拆分而不是全局切换。
CI 集成：把 Midscene 作为 Playwright 的一个测试步骤运行，MIDSCENE_REPORT=true开启报告，将 HTML 报告归档为构建产物，断言异常直接作为流水线失败信号。
缓存与耗时：开启MIDSCENE_CACHE后，相同界面状态下可复用已识别的元素位置，重复执行耗时明显下降；缓存以界面状态为键，UI 变更后自动失效，不需要手工清理。