Midscene.js：用自然语言写 E2E 测试，告别 CSS 选择器维护

Midscene.js：用自然语言写 E2E 测试，告别 CSS 选择器维护

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

上周前端改了一个 class 名，37 个回归用例当场从绿变红 😅 原因不是逻辑错了，而是脚本里每个 locator 都挂在那个 class 上。这事逼着我认真试了试 Midscene.js——一个 AI 视觉自动化框架：不写任何 CSS 选择器或 XPath，直接用自然语言操作页面。它不看 DOM，看的是截图。

当改个类名就能搞崩整个测试套件

传统浏览器自动化的痛点大家都熟：定位器写好了，UI 一改，定位器就死了。页面越复杂（虚拟滚动列表、动态挂载的弹窗、canvas 画出来的控件），你对着 DOM 越无力。Midscene.js 走的不是这条路——它把当前页面截图交给多模态模型，你用一句话描述"我想在这个画面上做什么"。只要人能看见的元素，它基本都能点到：只有图标没有文案的按钮、canvas 内容、跨域 iframe 里的东西，都在覆盖范围内。

它怎么工作：截图 → 规划 → 逐步执行

一次aiAct调用的流程可以概括成三步：

1. 读屏：对当前页面截图，交给视觉模型（Qwen-VL、Doubao-Seed、UI-TARS 等）识别按钮、输入框、链接的位置；
2. 拆解任务：模型把"搜索耳机并把第一件商品加入购物车"拆成一串原子操作，每一步都基于最新画面重新规划；
3. 执行与校验：动作完成后重新截屏确认状态，你还可以用aiAssert明确断言"购物车角标变成了 1"。

规划和定位的核心逻辑在 packages/core/src/ai-model/，每次执行会生成逐步报告，能看到每一步做了什么、点了哪里：

5 分钟跑通第一个用例

最短上手路径是装 npm 包（Web 平台用@midscene/web即可）：

npm install @midscene/web playwright

配合 Playwright，一个搜索加购用例只需要几行：

const agent = new PlaywrightAgent(page); await agent.aiAct('搜索"无线耳机"，打开第一个商品并加入购物车'); await agent.aiAssert('购物车中有 1 件商品');

前置工作有一点样板代码：Playwright 启动浏览器拿到page，配置模型环境变量（Base URL、API Key、模型名、MIDSCENE_MODEL_FAMILY）。细节见模型配置文档和Playwright 集成。如果连代码都不想写，Chrome 扩展可以直接在任意网页上试指令：

同一套指令，Web、Android、iOS 通吃

Midscene 不是浏览器专属工具。同一套aiAct/aiQuery/aiAssertAPI 在 Android、iOS、HarmonyOS 和桌面端原样可用，换端时脚本基本不用改。手机上跑"在美团下单咖啡"和 Web 上跑"搜索加购"，写法是一样的。

AI 认不出按钮时：三个常见坑 🐛

• 指令太含糊，模型会猜："点购物车"可能点到页面装饰图标上。给目标多补一点视觉上下文——颜色、相对位置、旁边的文案——命中率会明显上升。
• 目标小、容易混淆：小图标这种视觉特征弱的元素，开deepLocate多花一轮模型调用做深度定位。
• 长任务容易跑偏：复杂流程开deepThink加强任务拆解，并用setAIActContext全局注入背景知识，比如"如果出现 cookie 弹窗，先关掉它"。

它擅长什么，又该在哪些地方留神

说句公道话：选择器并没有出局。视觉自动化的代价是每一步都是真实的模型调用，更慢也更贵。三条实际体会：

1. 动态页面和复杂表单是它的主场：虚拟列表、动态弹窗、canvas 控件、跨端 UI——这些恰恰是选择器最难受、Midscene 最稳的场景；
2. 视觉断言是它独有的价值："折扣标签显示为红色"这种事，检查 DOM 节点存在与否是验不出来的，截图断言可以；
3. 大批量回归要算成本：一个 20 步的用例至少 20 次模型调用。对选择器稳定的固定页面，传统定位 + 关键步骤交给 AI 的混合写法往往更经济。

Midscene.js 本质上把"该点哪里"从一个编程问题变成了语言问题：你只需要描述界面长什么样，不用关心它在 DOM 里住哪。下次前端再改 class 名，你的用例大概还是绿的。

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