Midscene.js 零门槛上手指南用 3 个真实任务玩转 AI 视觉自动化测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene如果你经历过为选择器打工的夜晚——前端改了个 class 名整条测试用例就报废——那 Midscene.js 值得你花 5 分钟了解。它是一款面向 E2E 测试的 GUI Agent用 AI 视觉自动化测试的思路重写了 UI 自动化不依赖 DOM 与选择器只凭截图让 AI 理解界面、用自然语言执行操作。本文会用 3 个贴近真实工作的任务带你从零跑通全流程。先搞懂一件事为什么自动化总在修选择器传统 UI 自动化大多建立在读页面结构之上要么解析 DOM要么爬无障碍树再靠 CSS 选择器或 XPath 去定位元素。这套方案的脆弱点非常明显选择器是死的页面一重构#header .btn就失效维护成本全压在测试工程师身上结构是缺的纯图标按钮、自定义控件、canvas绘制的内容在 DOM 里根本没有语义工具看不见边界是窄的原生 App、跨域 iframe 往往够不着最关键的是结构无法回答界面看起来对不对——按钮位置、颜色高亮、布局错乱这些只有人眼能判断。Midscene.js 换了一条路只凭截图工作。你把具备 UI 定位能力的多模态模型接进来用自然语言描述目标AI 观察当前界面、规划步骤、定位元素并执行。只要人眼能看到的它就能定位。于是前面那些痛点——选择器失效、canvas、原生应用、视觉校验——被同一套机制一并解决。这套机制对外暴露为几个简洁的 API 家族API作用一句话理解aiAct规划并执行多步交互去把购物车清空并确认aiQuery从界面提取结构化数据把商品名和价格列出来aiAssert校验界面状态确认登录成功且显示欢迎语aiTap/aiInput等单步即时交互点这个按钮、填那个框下面这张图是它的通用 Playground 界面左侧输入自然语言指令右侧是被控制的真实页面Action / Query / Assert 三种模式一目了然。你可能会有疑问这些 API 到底怎么用别急接下来我们用 3 个任务逐个击破。 任务一让网页自己完成搜索 → 加购 → 校验假设你在做电商测试最频繁的回归就是搜索商品并加入购物车。传统写法要维护一串选择器而 Midscene 的写法是这样import { chromium } from playwright; import { PlaywrightAgent } from midscene/web/playwright; const browser await chromium.launch({ headless: true }); const page await browser.newPage(); await page.goto(https://www.example-shop.com); const agent new PlaywrightAgent(page); // 一句话完成搜索耳机 → 加购 → 确认数量 await agent.aiAct(搜索无线耳机把第一件商品加入购物车并确认购物车数量变为 1); // 提取结构化数据返回商品名与价格组成的数组 const items await agent.aiQueryArray{ name: string; price: number }( 列出购物车中的商品{name: string, price: number}[], ); // 校验界面断言购物车小计金额存在 await agent.aiAssert(页面显示购物车小计金额);环境前提Node.js 20.19以及一个支持 UI 定位的多模态模型 API Key。安装依赖只需一条命令npm i midscene/web playwright --save-dev这段代码里aiAct是最聪明的一个它会自主规划多步动作途中不断重新观察界面遇到弹窗也能绕过去aiQuery帮你把页面信息变成可直接断言的 JSON 数据aiAssert负责验收——条件不满足时直接抛错让测试真正起到拦截作用。小提示如果连项目都不想搭可以先安装 Chrome 扩展体验。打开任意网页在侧边栏输入点击登录按钮这类指令就能看到效果验证通过后把同样的指令迁移到上面的 Agent 代码里完全无缝衔接。任务二把手机 App 也交给 AI 驱动Web 只是起点。Midscene.js 对 Android、iOS、HarmonyOS 和桌面端提供同一套视觉驱动引擎——也就是说你在网页上学到的自然语言写法在手机上原样复用。以 Android 为例你只需要一台开启 USB 调试的设备或模拟器通过 adb 连接后启动 Playground就能看到下面的操作面板右侧是实时的手机画面左侧用自然语言描述任务AI 会先给出规划Planning再逐步执行。iOS 侧同样有对应的 Playground通过 WebDriverAgent 驱动真机或模拟器界面风格与操作逻辑保持一致更有意思的是一份 YAML 脚本可以在不同平台间复用详见任务三例如登录 → 断言欢迎页这种跨端用例只需切换脚本头部的平台声明核心步骤一字不改。 任务三不想写代码YAML 脚本加一行命令对于只是想验证某个流程通不通的场景维护一个完整测试工程显得太重。Midscene 为此提供了一套 YAML 脚本格式只写流程不碰框架。看下面这个例子你应该马上能读懂page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息安装命令行工具后用一条命令执行npm i -g midscene/cli midscene ./weather-search.yaml模型信息通过.env文件配置即可全程不需要写任何代码MIDSCENE_MODEL_BASE_URLhttps://你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY你的 API Key MIDSCENE_MODEL_NAME你的模型名称命令执行过程中会实时打印进度结束后自动生成可视化报告——每个步骤的截图、AI 的思考过程、提取的数据都会留存方便回溯与团队共享。⚡ 进阶玩法把工具用透的 5 个技巧到这里你已经掌握了最核心的 3 个能力网页脚本、移动端驱动、YAML 零代码流程。再分享 5 个让效率翻倍的进阶技巧用aiWaitFor处理动态加载页面数据是异步加载的与其写死sleep不如让 AI 等待条件成立。await agent.aiWaitFor(商品列表已经渲染完成, { timeout: 10000 })更稳、也更省时间。用deepThink/deepLocate提升稳定性当目标元素很小、或页面上容易混淆的元素较多时开启深度思考模式让模型多花一次调用拆解任务成功率明显上升。报告即调试执行结束后打开 HTML 报告每个操作步骤都有截图与说明点击 Open in Playground 还能把失败场景原样还原直接在可视化界面里重新调试省掉反复重跑的痛苦。用缓存减少重复调用同一页面在多次运行中的 AI 分析结果可以按配置复用策略支持 read-only / read-write / write-only跑量级回归时能省下不少 token 和时间。用 Bridge 模式接管真实浏览器当你需要在自己正在用的浏览器里执行自动化比如脚本与人工操作混用可以启动 Bridge 模式让本地 Agent 与浏览器建立连接边看边跑。⚠️ 新手避坑最常见的 4 个误区误区一随便选一个模型就开跑。不是所有多模态模型都擅长 UI 定位请选择官方文档中标注具备 UI 定位能力的模型如 Qwen、GLM-4V、UI-TARS 等否则元素定位准确率会大打折扣。误区二用单步 API 描述多步任务。在aiTap里写如果出现弹窗先关闭再点击结账是无效的——单步 API 只负责定位并执行固定动作这种带分支的流程请交给aiAct。误区三遇到 403 就怀疑工具坏了。用 Ollama 自托管模型时需要在环境变量里设置OLLAMA_ORIGINS*允许扩展访问Chrome 扩展执行失败时也先检查是否有其他扩展注入的 iframe 造成冲突。误区四担心数据隐私而不敢用。Midscene 支持自托管的开源模型如 UI-TARS敏感界面完全可以跑在本地截图数据不出内网。尾声下一步从这里开始回顾一下我们先看懂了为什么视觉方案能绕过选择器然后依次用网页脚本、移动端驱动、YAML 流程 3 个任务跑通了全流程最后补上了进阶技巧和常见坑位。对你而言最务实的下一步是——先装 Chrome 扩展用一条自然语言指令完成一次真实操作感受说人话就能测的体验再挑一个你最常回归的用例把它写成 YAML 或 Agent 脚本跑通。想深入源码或本地部署可以克隆仓库git clone https://gitcode.com/GitHub_Trending/mid/midscene。仓库内apps/site/docs/zh/目录下有完整的中文文档快速开始、YAML 脚本、各平台指南packages/下是各平台的实现源码apps/studio/则是一款基于 Electron 的桌面集成工具。社区的更新节奏很快多模态模型的视觉能力每代都在变强未来这套看屏操作的引擎大概率会延伸到更多你想象不到的设备上。现在打开你的浏览器输入第一句话试试吧。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考