Midscene.js：视觉驱动的 GUI Agent 端到端测试框架｜2026实战解析

Midscene.js：视觉驱动的 GUI Agent 端到端测试框架｜2026实战解析

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

Midscene.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(...)调用，在浏览器和手机上跑的是相同的规划逻辑，你只需要换掉底层连接方式：

官方还提供 Playground（Chrome 扩展或各平台 Playground 窗口），让你在不写代码的情况下先验证一句指令的效果，再把它搬进脚本。

⏱️ 从零跑通：5 分钟看到第一份可视化报告

第一步：配置模型

Midscene 通过 4 个环境变量找到你的多模态模型，在项目目录建一个.env即可：

# .env：dotenv 约定，不加 export MIDSCENE_MODEL_BASE_URL="https://你的模型服务地址/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.ts：

import { 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