Midscene.js视觉驱动的 GUI Agent 端到端测试框架2026实战解析【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个基于视觉的 GUI Agent 端到端测试框架你用自然语言描述操作目标它像人一样看截图、找元素、点按输入并在 Web、Android、iOS 等平台上复用同一套 Agent API运行结束后自动生成可回放的 HTML 报告。如果你正在维护 E2E 自动化脚本、被选择器维护问题拖累这篇实战解析会从安装配置讲到跨端场景与成本优化。 按钮挪了个位置你的 E2E 脚本还能跑吗上周电商项目的 QA 同事跑回归时发现商品卡的加入购物车按钮换了配色列表顶部还多了一个活动弹窗12 条脚本里 7 条因为 XPath 失效直接报错。他花了一整天核对元素位置才把用例修完。Midscene.js 解决的就是这类问题它把看屏幕—做操作—验证结果这套人的使用方式建模给多模态模型你写的是在搜索框输入 Headphones 并回车而不是第 3 层 div 下第 2 个 span。 Midscene.js 能替你完成哪些事用自然语言做交互和断言aiAct接收一个目标自主规划步骤、定位元素并执行直到目标达成。你省下的是逐步拆解流程的代码和整条定位链路。aiTap/aiInput/aiScroll等即时交互 API一次调用只做一个动作适合路径固定、只需替换个别步骤的场景。aiAssert用一句话描述期望界面条件不成立就抛错并附带模型判断原因。你省下的是大量page.textContent式的断言代码。aiQuery从界面提取结构化数据提示词里写明结构即可拿到数组或对象不需要手动解析 DOM。一套 Agent API 覆盖 Web 与移动端同一个agent.aiAct(...)调用在浏览器和手机上跑的是相同的规划逻辑你只需要换掉底层连接方式平台集成包前置条件Webmidscene/webPlaywright / Puppeteer一个已打开的页面实例Androidmidscene/android设备通过 adb 连接iOSmidscene/ios已部署 WebDriverAgent官方还提供 PlaygroundChrome 扩展或各平台 Playground 窗口让你在不写代码的情况下先验证一句指令的效果再把它搬进脚本。⏱️ 从零跑通5 分钟看到第一份可视化报告第一步配置模型Midscene 通过 4 个环境变量找到你的多模态模型在项目目录建一个.env即可# .envdotenv 约定不加 export MIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的APIKey MIDSCENE_MODEL_NAME你的模型名称 MIDSCENE_MODEL_FAMILY你的模型系列支持的模型Qwen、Doubao-Seed、GLM、Gemini、UI-TARS 等与完整配置见仓库文档 model-common-config。第二步写一个最小脚本需要浏览源码或示例时clone 一份仓库即可git clone https://gitcode.com/GitHub_Trending/mid/midscene。否则直接装依赖并保存demo.tsimport { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; import dotenv/config; const browser await chromium.launch({ headless: true }); const page await (await browser.newContext()).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 agent.aiAssert(页面左侧有分类筛选栏); await browser.close();这一行new PlaywrightAgent(page)替你把截图采集、元素定位和动作执行全部挂到了现有 Playwright 页面上其余代码就是自然语言。第三步运行并查看报告npx tsx demo.ts控制台打印结构化商品列表并输出Midscene - report file updated: .../xxx.html浏览器打开该文件就能看到每一步的截图、AI 决策过程和断言结果 场景深潜从单页操作到 Android 真机场景一竞品页面的批量价格提取业务目标是每晚抓取竞品耳机列表并入库。核心调用就是上面脚本里的aiQuery再把结果写文件即可。两个容易踩的坑价格默认可能带货币符号返回。把金额只返回数字这类输出要求放进提示词或在创建 Agent 时设置aiContexts.default让所有模型调用共享这份业务规则。页面状态不确定时比如广告位轮换在aiQuery前加await agent.aiWaitFor(列表已加载完成)用视觉等待替代固定 sleep。场景二同一套流程跑在 Android 设备上目标是验证 Web 侧跑通的商品搜索流程在 App 侧的表现。只需把 Playwright 连接换成 adb 设备import { AndroidAgent, AndroidDevice, getConnectedDevices } from midscene/android; const device new AndroidDevice((await getConnectedDevices())[0].udid); const agent new AndroidAgent(device); await device.connect(); await agent.aiAct(打开浏览器进入 ebay.com搜索 Headphones 并回车); const items await agent.aiQuery( {itemTitle: string, price: number}[], 找出商品及对应价格, ); console.log(items);同样的aiAct/aiQuery签名你换的只是第一行的设备连接。运行前确认adb devices -l能列出设备且设备已信任电脑部分机型需要在开发者选项里同时开启USB 调试安全设置否则注入点击事件会直接报权限错误。部分 WebView 输入框会监听 ESC 事件Midscene 输入后默认发 ESC 收起键盘可能把刚输入的内容清空。遇到这种输入框参考文档切换键盘收起方式。⚡ 效率杠杆把模型调用成本和耗时压下来启用规划与定位缓存new PuppeteerAgent(page, { cache: { id: my-script } })缓存aiAct的规划步骤和元素 XPath命中时省去重复模型调用。官方文档中有一个案例把执行耗时从 51 秒降到 28 秒缓存文件落在./midscene_run/cache。生产环境用只读策略cache: { strategy: read-only, id: ... }加手动await agent.flushCache()避免运行时意外污染已验证的缓存。小目标加deepLocate: true图标按钮、视觉特征不明显的元素多一轮模型调用定位更稳。固定流程少用aiAct路径确定的操作拆成aiTap/aiInput/aiQuery组合aiAct每步都基于最新界面重新规划时间和 token 都更高。失败先看报告HTML 报告里有每一步的截图和模型推理排查断言失败不用再靠猜。 延伸路径接下来你可以继续读想把 Midscene 嵌进现有 Playwright 测试用例而不是独立脚本看 集成到 Playwright里面有playwright.config.ts的完整改法。想让流程用 YAML 描述、工程步骤用 TypeScript Node 编写看 Midscene Test 概览它提供生命周期钩子、重试和并发隔离。想搞懂缓存的失效与回退机制再回头看 缓存 AI 规划和定位。下一步建议先用 Chrome 扩展 Playground 把你最常维护的三条用例改写成自然语言指令验证通过后再逐条迁到脚本里。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考