Midscene.js 实战指南：用 AI 视觉测试把回归脚本维护量降下来

Midscene.js 实战指南用 AI 视觉测试把回归脚本维护量降下来【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene场景切入凌晨两点nightly 任务全红。200 条回归用例六成挂在同一步在搜索框输入关键词——一次 A/B 实验改了搜索页结构新模板给输入框多包了一层 span#search-input和text搜索全部失效。我修选择器修到五点修完 A/B 平台又回滚了。Midscene.js 是一个做端到端测试的 GUI Agent用 AI 视觉测试代替选择器来定位元素就是冲着这类场景来的。选择器定位最真实的成本不在写脚本而在跟着页面结构打地鼠。动态渲染、A/B 实验、灰度发布任何一次前端改动都可能让一批用例的位置漂移。Canvas 绘制的图表控件、纯图标的按钮、跨域 iframe 里的表单这些区域基本没有稳定选择器可抓传统 DOM 定位手段覆盖不到只能退回手动测试。Midscene 的思路是把定位问题从DOM 里找标签换成屏幕上找东西对页面截图交给视觉模型判断元素在哪、该点什么、结果对不对。你写的是搜索耳机筛选出 100 美元以下的结果它自己找搜索框、自己输入、自己断言。问题不是脚本写得不够多而是定位方式本身到天花板了。架构拆解clone 下来打开仓库这是一个 pnpm monorepo模块划分比较直白packages/coreAgent 核心截图、任务规划、定位、报告都在这一层packages/web-integrationPlaywright、Puppeteer、Chrome 扩展桥接等 Web 端集成packages/cli、packages/testYAML 脚本运行器和 AI 测试框架packages/android、packages/ios、packages/harmony、packages/computer各平台设备适配apps/Playground、Studio 桌面端、报告站点等周边应用 一条指令从输入到执行经过哪几个阶段以agent.aiAct(搜索耳机筛选 100 美元以下)为例指令会依次经过这几步截图准备对当前页面截图做必要的裁剪和缩放作为模型的眼睛任务规划核心 Agent 模块 里的任务构建器把自然语言拆成多步操作计划task-builder.ts、tasks.ts这一步可以命中本地缓存元素定位每步操作前重新看图视觉模型给出目标区域Web 端可以叠加 DOM/XPath 加速执行动作通过设备抽象层把点击、输入、滚动下发给具体平台浏览器、ADB、WDA 等记录与报告每一步的截图、模型决策、耗时都写进执行会话最后由report-*.ts系列生成 HTML 报告整个过程里模型调用是主要开销所以规划结果和元素定位都做了缓存task-cache.ts、cache-config.ts下次跑同样的指令直接复用失效再自动回退给模型重算。除了浏览器它也能通过 Chrome 扩展桥接层 直接接管你桌面上正在用的 Chrome复用登录态和插件适合需要人在环中的调试场景和选择器定位的关键差异维度选择器定位Midscene 视觉定位适用场景元素定位方式CSS/XPath/文本截图 自然语言描述页面结构不稳定时维护触发条件DOM 结构变化即失效视觉可辨识性变化才失效A/B 频繁的实验页Canvas、纯图标按钮需要额外埋点或近似选择器直接按外观描述图表、自定义控件结构化数据提取逐字段解析 DOM一句话描述模型返回 JSON结果列表、表单回读定位方式不同带来的直接变化用例维护从跟着 DOM 走变成跟着视觉走。只要用户能看到的Agent 就能操作DOM 怎么改只要页面上还画着一个搜索框用例就不用动。从 0 到跑通装依赖与环境准备先 clone 仓库看代码本仓库只读用来翻实现git clone https://gitcode.com/GitHub_Trending/mid/midscene在你的测试工程里装运行时的依赖npm i -D midscene/web playwright playwright/test tsx然后在工程根目录放一个.env模型配置只需要三行MIDSCENE_MODEL_API_KEY你的key MIDSCENE_MODEL_NAME模型名 MIDSCENE_MODEL_BASE_URL服务地址写第一条自然语言用例新建demo.ts核心就三行——先改导入再跑npx tsx demo.tsconst agent new PlaywrightAgent(page); await agent.aiAct(搜索耳机把结果筛选到 100 美元以下); await agent.aiAssert(搜索结果里每个商品价格都低于 100 美元);page是你自己用 Playwright 打开的页面。注意一点aiAct之前给页面留够加载时间否则模型看到的是半加载的截图断言会飘。挂进 Playwright 测试框架如果是已有的 Playwright 工程用 fixture 方式接入改fixtures.ts里注册ai这一步test.use({ ai: async ({ page }, use) use(new PlaywrightAgent(page)) }); test(搜索筛选, async ({ ai }) { await ai.aiAct(搜索 headphones); await ai.aiAssert(列表已按筛选条件刷新); });记得把timeout放宽到 90 秒上下视觉断言比选择器断言多花几秒是常态。看运行结果报告跑npx playwright test控制台末尾会打印一行报告文件路径。用浏览器打开那个 HTML每一步都有截图、元素定位框和断言结果失败时你能直接看到模型当时看到了什么画面排查体验比看 DOM dump 直观得多实测与对比我们拿文档里那个 eBay 耳机搜索流程跑了两种配置同一条aiActaiAssert指令不开缓存和开启缓存各跑若干轮取均值。搜索流程耗时对比开缓存 vs 不开缓存配置单轮耗时主要开销不开缓存约 7.8 秒模型规划 逐元素定位缓存命中约 0.9 秒缓存复用的规划与 XPath仓库文档里另一个更复杂的场景是从 51 秒降到 28 秒。幅度取决于流程里重复执行的规划步骤占比步骤越多、页面越稳定缓存收益越大。时间花在哪瓶颈与调优点模型调用是绝对大头。每个aiAct至少一次多模态调用定位失败重试还会叠加。调优第一手段是缓存配置cache: { id: case-id }默认 read-write 策略会自动读写规划和视觉可以分工。复杂流程用规划模型 轻量视觉模型的组合简单点击用便宜模型成本能压下去一截断言结果永远不缓存。aiAssert、aiQuery这类读取当前页面状态的调用每次都走模型这是刻意的——你不需要断言结果是新鲜的缓存失效是自动的。XPath 复用前会先验证有效性失效就回退模型重定位不会悄悄用错位置能省多少维护成本换算一个粗略的估算公式维护人天 用例数 × 单次修脚本平均耗时 × 年页面迭代次数 ÷ 8按 200 条用例、平均每条修复 15 分钟、一年迭代 20 次算200 × 0.25h × 20 ÷ 8 ≈125 人天/年花在改选择器这一件事上。切到视觉定位后DOM 重构不再触发用例修改这个开销大部分消失剩下的主要是自然语言描述的措辞修正。模型费用是新增成本仓库文档披露过一组参考数据AppControlBench 的 60 个任务全流程模型成本约 0.59 美元日回归场景下每天几块钱到几十块钱的量级和 125 人天放在一起账不难算。踩坑清单️ 视觉断言为什么在 Canvas 页面上会飘Canvas 内容虽然不在 DOM 里但截图断言反而覆盖得到真正的问题是截图本身动画帧、粒子效果、视频画面会让断言看到的画面和用户看到的画面不一致。我们后来的做法是断言前加一句aiWaitFor(页面动画结束数据稳定)避免在过渡帧上采图另外 headless 下字体渲染偏糊把 viewport 设成 1280×768 并固定deviceScaleFactor后小字号文本的识别明显稳定。缓存开了之后XPath 漂移怎么排查一开始我们在 CI 里所有机器都用 read-write 缓存很快发现偶发红A 机器写入的 XPath 在 B 机器的页面结构下已经失效回退逻辑救回了定位但报告里一片cache miss看起来像坏了。后来改成只有一台机器 read-write 写缓存其余全部strategy: read-only冲突就消失了。另外记住一条缓存里存的 XPath 每次都会先验证再复用验证不过就回退模型所以缓存不是免检它省的是重复思考不是正确性保证。并行跑的时候浏览器实例怎么管Playwright 多 worker 并行时每个 test 有独立page一个 test 里只挂一个 Agent基本不踩坑。真正出过事的是调试 bridge 模式它接管的是桌面 Chrome 的标签页同一时间只支持一条连接多个脚本并发连过去会互相抢页面。我们的处理是 bridge 模式只用于单人调试CI 一律走 Playwright 无头实例。为什么报告里的截图模糊、断言跟着不准报告截图和模型看到的是同一份图图糊了定位就飘。两个来源一是 headless 默认 1x 缩放下中文小字号发虚二是某些页面有 CSS 缩放。改deviceScaleFactor: 2重跑一轮对比报告多数看走眼的断言就恢复了。如果页面本身设计就是低对比度小图标那属于视觉定位的适用边界见下一章。边界与下一步当前这套方案的局限说清楚比较好单次断言的耗时和成本仍然高于选择器。秒级 vs 毫秒级纯静态页面的高频用例全量切视觉并不划算适合结构不稳定 用例数量可控的混合策略视觉定位对小图标、高密度密集文本的容错有限。点击右上角那个 12px 的关闭图标这类描述模型也会犹豫描述需要具体到颜色和相对位置DOM 加速定位目前只在 Web 端生效。Android、iOS、HarmonyOS、桌面端走的是纯视觉路径缓存收益结构不同项目自身在往前走的两个方向Midscene Test 框架midscene/testBetaYAML 声明式写用例 TypeScript 自定义 Node 做数据准备自动把注册的 Node 编译成 Markdown 文档人和 AI 能读同一份说明共同维护用例跨平台同一套 Agent APIWeb、Android、iOS、HarmonyOS、桌面共用aiAct/aiAssert这组接口社区还长出了 Python、Java 等语言的 SDK那条 nightly 任务现在 22:00 就绿了。下一次搜索页再改版要改的是几条用例里的自然语言描述不是 200 个选择器第二天早上不用再爬起来救火翻一眼报告确认全绿就可以去喝咖啡了。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考