Midscene.js实战指南：用视觉AI写出E2E测试

Midscene.js实战指南：用视觉AI写出E2E测试

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

Midscene.js 是一个面向 E2E 测试的 GUI Agent，你用自然语言写指令，AI 靠截图定位元素并执行操作。本文以一个冒烟测试任务为主线，讲清从接入到看报告的完整用法，适合前端与测试新手。

任务背景：选择器又失效了

想象这样一个场景：你负责维护商城站点的主流程回归测试，上个月前端重构一次，选择器就坏了三十个；纯图标的筛选按钮用 XPath 怎么写都找不到，Canvas 画出来的商品图墙更是完全不可见。每改一次 UI，就得跟着改一轮脚本，测试套件的维护成本比写测试本身还高。

Midscene.js 换了条路：它不看 DOM，也不读无障碍树，只盯截图。人眼能看见的位置它就能定位——图标按钮、Canvas、跨域 iframe 都行，还能验证用户"真正看到的"效果，比如高亮颜色、布局是否错乱。这篇文章就用它完成一个任务：打开商城站点、搜索耳机、确认搜索结果展示出来，并把商品标题和价格抽成结构化数据。

🚀 首次上手：Playwright 接入 Midscene

先用包管理器安装@midscene/web和 Playwright，并配好模型密钥（Midscene 需要带 UI 定位能力的多模态模型，云服务或自托管开源模型都可以）。

然后启动浏览器页面，把它交给PlaywrightAgent，就能开始下达指令：

const agent = new PlaywrightAgent(page); await agent.aiAct('搜索"无线耳机"并打开第一个商品'); const price = await agent.aiNumber('第一个商品的价格'); await agent.aiAssert('页面右上角存在购物车图标');

这几类 API 基本覆盖日常场景：aiAct接一个目标、自主规划并执行多步动作；aiQuery、aiNumber、aiString负责从页面里抽数据；aiAssert做 AI 断言，失败直接抛错。如果暂时不想写代码，也可以装 Chrome 扩展，在浏览器侧边栏里直接试用同样能力，先把指令措辞验证清楚，再搬进脚本：

第一条指令跑通后，主链路就通了。完整流程见 Playwright 集成文档；如果你连 JS 工程都不想做，还可以用.yaml文件描述整个流程，从命令行直接执行，非开发同学也能读写。

👁️ 观察执行：可视化报告

每次跑脚本，midscene_run目录下都会自动生成报告文件。打开后能看到每一步的截图、模型规划、token 消耗和执行耗时，相当于给这次测试拍了一段"逐帧回放"：

测试失败时它最有价值：你能直接看到 AI 失败那一刻"看到"的画面——是弹窗没关，还是页面没加载完——而不是对着日志猜。调试时还可以打开模型调试模式查看发给模型的真实 prompt，一眼定位问题。团队协作时把报告文件发过去就行，不用再录屏。

📱 同一套 API 打到移动设备

任务的第二站是把同样的回归流程放到 Android 真机上。Midscene 的 Android、iOS、HarmonyOS 和桌面平台共用同一套 API，接入设备后写脚本的方式几乎不变：

import { AndroidAgent } from '@midscene/android'; const agent = new AndroidAgent(); await agent.aiAct('打开汽车资讯 App 并搜索"小米 SU7"'); const params = await agent.aiQuery('{ name: string, value: string }[], 提取参数表');

Android 底层走 adb + scrcpy 拿截图，iOS 走 WebDriverAgent，Web 走 Playwright 或 Puppeteer，但脚本层面只是换了一个 Agent 类。接好设备后还能打开对应平台的 Playground，用自然语言指令先手动验证一遍：

⚙️ 省钱提速的设置：缓存与模型选择

视觉自动化的成本大头是模型调用，有两项配置值得了解。

缓存：同一个指令反复跑时，可以开启缓存。Midscene 会存下执行计划，以及 Web 端元素定位信息，缓存失效时自动退回 AI 重新识别。官方文档里有个例子，同一任务启用缓存后执行时间从 51 秒降到 28 秒：

const agent = new PlaywrightAgent(page, { cache: { id: 'mall-smoke-test' }, // 首次运行后写缓存 });

注意查询类 API（如aiQuery、aiAssert）的结果永远不会被缓存，保证数据是实时的。细节看缓存文档。

模型选择：大多数场景一个带 UI 定位能力的 Default 模型就够了；只有在复杂多步规划或大批量数据抽取时，才需要额外挂一个 Planning 或 Insight 模型。纯视觉路线的好处还在于，token 消耗只跟页面分辨率和任务复杂度相关，不随 DOM 节点数量膨胀。数据敏感的场景也可以自托管 Qwen-VL、UI-TARS 这类开源模型，做到全程离线。

🧭 常见踩坑点与快速答疑

最后汇总几个实际用下来最常碰到的问题：

• 想复用自己已登录的 Chrome？用桥接模式：本地脚本连上你桌面上的 Chrome，Cookie 和扩展状态全部可用，模型配置写在 Node.js 侧。完整示例见桥接模式文档。
• 页面动画多、加载慢？操作后用aiWaitFor('搜索结果已展示')等一个具体状态，比固定 sleep 可靠；任务复杂时给aiAct开deepThink，让模型规划前想得更细。
• 元素太小、老是点不准？给定位类调用开deepLocate，多轮精细定位，小目标的成功率会明显提升。
• 支持别的语言吗？核心包是 TypeScript，社区还有 Python、Java 等 SDK；CI 里已有 JS 环境的话直接就能接。

核心引擎、多平台适配层和报告模块都在仓库里，从 packages/core/src 目录读源码，能看懂"一张截图如何变成一次操作"的完整链路。想系统学 API，从官方文档的 Basics 一篇开始就够了。

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