Midscene.js：用一句自然语言指令驱动浏览器与移动端 UI 自动化

Midscene.js用一句自然语言指令驱动浏览器与移动端 UI 自动化【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene写 E2E 测试的工程师大概率被 Midscene.js 吸引过它用视觉驱动的方式操作 UI你只需要像跟新人交代任务一样写在搜索框输入 Headphones 并回车剩下的点击、等待、提取数据都由它完成。测试套件会不会因为别人改了个 class 名而全挂传统 UI 自动化的定位全靠选择器id、class、XPath、坐标。只要前端重构一次把className从btn-primary改成btn-new-primary你的用例就集体变红。更麻烦的是选择器够不着的地方纯图标按钮、canvas画出来的界面、原生 App、跨域 iframeDOM 里根本读不到语义信息测试框架对它们是盲的。还有一类需求是选择器天生答不了的页面上看起来对吗比如商品卡片是否高亮、结算按钮是否置灰。断言 DOM 节点存在不等于断言用户看到的画面正确。Midscene.js 的思路是把读结构换成看画面。它截屏交给视觉语言模型模型返回元素位置再模拟点击、输入。定位不依赖任何页面结构所以重构、图标按钮、原生 App 都不再是问题。它覆盖 Web、Android、iOS、HarmonyOS 和桌面端共用一套 API。不读 DOM一次看截图→规划→动手的循环aiAct是核心入口。它拿到一句自然语言目标后做的事是截图、让模型基于画面规划下一步、定位元素、执行动作然后再截一张图确认结果如此循环直到目标完成。这意味着每一步都基于最新画面做决策弹窗突然冒出来它下一轮就会先处理弹窗而不是机械地按事先写死的步骤硬走。和规划型相对的是一组即时操作 APIaiTap、aiInput、aiScroll这类一次定位、一次动作不规划多步流程速度快、调用省aiWaitFor则负责等待某个画面条件成立替代写死的 sleep。观察类 API 如aiQuery可以从截图里提取结构化数据aiAssert断言的是用户实际看到的内容而不只是节点存在。想不写代码先感受一遍可以用官方 Playground配好模型后在网页里输入指令直接执行所有 API 都能即时看到效果。定位逻辑的主体在packages/core/src/agent/下模型调用封装在packages/core/src/ai-model/读源码时按这条线走比较顺。让模型只思考一次计划与定位结果可以缓存视觉驱动有一个绕不开的成本问题每次执行都在烧模型调用。Midscene 的做法是缓存两类结果。一类是aiAct的执行计划同一条指令在相似的页面环境下会走同样的步骤第一次规划完存下来之后直接复用。另一类是 Web 平台的元素定位结果用 XPath 存下来下次先校验它还有效就直接用无效再回退给模型重新分析。官方文档里有一个案例同一脚本开启缓存后执行时间从 51 秒降到 28 秒缓存文件落在./midscene_run/cache目录。需要注意缓存默认是关闭的要显式配置cache: { id: xxx }才生效aiQuery、aiAssert这类查询结果永远不走缓存保证每次拿到的都是实时画面信息。十分钟跑通第一次自动化仓库是 monorepo想读源码或贡献代码的话先克隆它git clone https://gitcode.com/GitHub_Trending/mid/midscene然后pnpm install构建各包。但只是想跑起来最短路径是直接装 npm 包两步搞定npm install midscene/web playwright tsx echo OPENAI_API_KEYsk-your-key .env新建demo.ts把下面的内容存进去——搜索一个电商页面并提取商品数据import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; const browser await chromium.launch({ headless: false }); const page await browser.newPage(); await page.goto(https://www.ebay.com); const agent new PlaywrightAgent(page); await agent.aiAct(在搜索框输入 Headphones 并回车); const items await agent.aiQuery({itemTitle: string, price: number}[] 列出页面上所有商品和价格); console.log(items); await browser.close();运行npx tsx demo.ts浏览器窗口会自己打开、自己搜索终端打印出商品和价格。跑完后终端会输出一条报告文件路径浏览器打开就能看到每一步的截图、规划和耗时。挑一个场景用起来给存量 Playwright 用例加视觉断言已有测试工程只需要装midscene/web把test实例换成PlaywrightAiFixture()扩展出来的版本reporter 里加一行midscene/web/playwright-reporter。之后用例里除了选择器还可以写aiAssert(购物车显示一件商品且有 subtotal)。值得用的点老用例一行不用动视觉断言按需加迁移成本几乎为零。用 YAML 脚本跑冒烟测试不写代码的同事也能维护脚本一个 YAML 就是一个可执行用例page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今天的天气 - sleep: 3000 - name: 校验结果 flow: - aiAssert: 结果页显示了天气信息装好 CLI 后直接执行文件即可。适合每天跑一遍、确认主流程没挂的场景脚本改动不需要重新发版测试工程。连一台真机做 Android 回归原生 App 没有 DOM传统框架要写 UiAutomator 脚本Midscene 只需要 USB 调试开启、adb 能识别设备然后照样是aiAct(打开应用搜索东京的酒店)。这是纯视觉定位最能打的地方模型看到的和用户看到的完全一致。midscene/android包负责设备通信源码在packages/android/src/agent.ts。你大概率会碰到的几个问题aiAct跑很久或超时任务目标太大模型多轮规划拖长了时间。拆成几个小aiAct或调高replanningCycleLimit默认 20 轮。小图标、外观相近的元素点错视觉特征太弱单次定位不够准。给这次调用加deepLocate: true它会多走一轮定位。aiAssert在页面刚加载完就失败内容还没渲染完就去断言。把固定 sleep 换成aiWaitFor(出现某某内容)等条件成立再继续。重复执行慢怀疑缓存没生效缓存默认关闭没配cache选项就每次全量调模型。在 agent 配置里加cache: { id: my-cache }。报告里的截图打不开用了html-and-external-assets输出格式这种报告依赖相对路径加载本地图片file://协议会被浏览器拦掉。在报告目录跑npx serve再用 http 访问。三周上手路线第一周把上面的 demo 跑顺再按 Playwright 集成的方式接进一个真实测试工程重点体会aiAct/aiQuery/aiAssert三件套的边界——什么时候该用即时操作什么时候才值得让 AI 规划。顺手读一下packages/web-integration/src/playwright/看 Agent 是怎么挂在 Playwright 页面实例上的。第二周进入核心层。packages/core/src/agent/里的规划循环是重点配合packages/core/src/ai-model/看请求是怎么组装、模型返回怎么解析成坐标的。缓存机制的实现在这条链路上读完再决定自己项目里怎么配缓存策略。第三周横向扩一个平台或做一个定制需求。packages/android/src/agent.ts展示了设备层怎么接进来packages/core/src/report.ts是报告生成的入口想改报告样式或加指标从这里下手。Midscene.js 的定位很清楚用视觉模型替代选择器让 UI 自动化只关心看到什么、做什么。最快的下一步就是照第二节的 demo 跑一遍然后打开它生成的 HTML 报告逐步看看 Agent 究竟是怎么理解页面的。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考