Midscene.js 实战指南零门槛用 AI 视觉自动化跑通第一个 E2E 测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene写 E2E 测试最崩溃的瞬间往往不是断言失败而是页面一改版几十个 selector 集体失效图标按钮没有文案、canvas上画出来的组件拿不到 DOM、跨域 iframe 里的元素选不到。Midscene.js 就是为了解决这类问题而生的 AI 自动化测试工具它像一个“会看屏幕的人”靠截图理解界面你用自然语言描述要做什么、期望看到什么它就规划步骤、定位元素、执行操作并校验结果同一套 API 覆盖 Web、Android、iOS、HarmonyOS 和桌面端。核心原理一句话每次操作前先看一眼屏幕把任务说给 AI 听让 AI 决定点哪里、输什么、页面是否符合预期。这意味着你不再需要写选择器也不用给界面加测试标注。项目速览这是一个“能看屏幕的测试代理”Midscene.js 把 AI 的 GUI Agent 和一套完整的测试工具链打包在一起用aiAct执行自然语言描述的操作流用aiQuery从界面上提取结构化数据用aiAssert做视觉断言运行完自动生成带截图和 AI 决策过程的 HTML 报告。适合正在被“selector 脆弱性”折磨的测试工程师、想给 App 做自动化但不懂控件树的开发者以及希望在现有 Playwright/Puppeteer 体系里增量引入 AI 能力的团队。场景适配度速查表典型场景是否适合原因或建议Web 复杂表单、动态页面的回归测试✅ 适合无 DOM 依赖页面改版不用改脚本Android / iOS App 功能测试✅ 适合同一套 Agent API通过 adb / WDA 连接真机或模拟器纯canvas、图标按钮、跨域 iframe 内操作✅ 适合这类元素传统选择器基本无解视觉定位是正解页面上的结构化数据提取、监控巡检✅ 适合aiQuery直接按 schema 返回 JSON高频、纯静态页面上的极致性能型操作⚠️ 权衡每次操作都要过一遍多模态模型延迟和成本高于原生 Playwright建议只把 AI 能力用在视觉断言和难定位的元素上快速上手最短路径跑通第一个脚本不用从零搭项目装一个 CLI、配一个模型、写一个 YAML 就能出报告。本节给出 Web 场景的最小闭环细节可查官方文档 快速开始 和 YAML 脚本运行器。环境要求清单️ Node.js20.19/22.12/24较旧的 Node 20 patch 版本会被执行链路的工具链拒绝 一个具备 UI 定位能力的多模态模型 API KeyQwen、Doubao、GLM、Gemini、GPT 等均可也支持自托管开源模型 能访问该模型服务的网络环境第一次跑通CLI 一条 YAML 命令第一步配置模型。在项目运行目录下创建.env注意 dotenv 约定不加export前缀以豆包为例MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed第二步写一个bing-search.yaml再安装 CLI 并执行page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息npm i -g midscene/cli midscene ./bing-search.yaml如何确认它跑通了终端会实时打印每一步的执行进度命令结束后生成一份交互式 HTML 报告打开后能看到每一步的截图、元素定位框、AI 的决策理由和aiAssert的通过情况。看到“结果显示天气信息”这一步标绿就说明视觉断言已经生效。如果你不想写任何代码只想先体验也可以装 Chrome 扩展版 Playground在侧边栏直接输入自然语言指令试跑见 快速开始。三个高频实战场景从 Web 回归到 App 自动化以下三个场景覆盖了绝大多数团队引入 Midscene.js 的动机每个都按“何时用 / 怎么配 / 怎么验证”展开。场景一Web 应用的 AI 回归测试什么时候用现有 Playwright/Puppeteer 用例因为页面改版频繁挂掉或者要测的表单里有大量自定义组件、弹层、canvas。操作要点用PlaywrightAgent接管已有的page对象即可接入现有测试框架不需要重写用例结构。多步骤、路径不确定的任务交给aiAct结果校验用aiAssert写“用户看到的最终样子”例如“选中方案有蓝色边框和对勾”。完整集成方式见 Playwright 集成指南。const agent new PlaywrightAgent(page); await agent.aiAct(搜索耳机筛选价格低于 100 美元的结果); await agent.aiWaitFor(筛选后的商品列表已展示); await agent.aiAssert(每条商品的价格都低于 $100);如何验证生效运行后打开 HTML 报告逐步核对截图与断言结论断言不成立时报告会明确给出模型判定不通过的原因方便区分“真 bug”和“脚本写得不对”。场景二Android App 的免控件树测试什么时候用要给 App 做功能回归但不想依赖控件树、也不想让开发团队加测试 ID典型如地图导航、订酒店、刷信息流这类多步骤操作。操作要点手机开启 USB 调试并连上电脑用adb devices拿到设备号写进 YAML后续全部用自然语言描述流程android: deviceId: s4ey59 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 杭州西湖然后点击搜索 - ai: 点击第一个搜索结果进入详情页 - ai: 点击 路线 按钮进入路线规划页面如何验证生效命令执行期间adb侧可看到界面被真实驱动结束后的报告里每个ai步骤都有对应截图逐帧对照即可确认 App 确实走到了预期页面。想零代码先试一遍流程可用 Android Playground 在浏览器里连真机直接发指令。场景三视觉断言 结构化数据提取什么时候用需要盯住页面上“看得见但选不到”的东西——价格、库存数字、选中标记、报错提示或者要把一个列表页的内容拉成 JSON 做监控比对。操作要点aiQuery的提示词里直接写清数据结构和类型返回值就是可用的 JS 对象aiBoolean适合做布尔巡检“登录弹窗是否可见”aiAssert条件不成立会直接抛错天然适合放进 CI 当卡点const items await agent.aiQueryArray{ name: string; price: number }( 购物车中的商品{name: string, price: number}[], ); await agent.aiAssert(购物车中有一件商品且页面显示了小计金额);如何验证生效aiQuery的返回直接参与后续代码逻辑打印、落库、比对基线数据不对一眼可见aiAssert在 CI 中失败即红灯报告里能查到当时的截图证据。实战技巧与调优先省钱再提速调优的核心思路是能确定的步骤不用 AI 规划需要 AI 的步骤给足定位精度。两条实践建议——其一操作流程稳定且明确的分支用 JavaScript 逐步编排aiQuery 循环 aiTap只在路径不确定处调用aiAct可以显著降低 token 消耗和延迟其二复杂任务才打开增强开关deepThink把任务拆解、规划、定位拆成多次模型调用提升复杂流程稳定性deepLocate增加一次定位调用专治目标元素小、周围干扰项多的场景。await agent.aiAct(完成结账表单在下单前停止, { deepThink: true, deepLocate: true, context: 如果出现地址确认弹窗请选择默认收货地址。, });模型选型上README 给出的公开基准里 Midscene 在 AppControlBench 的 60 个任务总成本约 $0.59Doubao Seed 2.1 Turbo 配置下说明截图驱动的交互路径并没有把 DOM 树塞给模型成本可控团队也可以按“规划用强模型、定位用轻量模型”的组合进一步压成本。常见坑现象、原因与处理现象扩展里运行报Cannot access a chrome-extension:// URL of different extension。原因其他 Chrome 扩展向页面注入了iframe或script与 Midscene 冲突。处理在开发者工具里找到该标签按扩展 ID 到chrome://extensions/禁用冲突扩展后刷新页面。现象用 Ollama 自托管模型时请求返回 403。原因Ollama 默认拒绝来自 Chrome 扩展的跨域来源。处理启动 Ollama 时设置环境变量OLLAMA_ORIGINS*。现象执行 YAML 时 Rspack 报Unsupported Node.js version。原因Node 版本过旧例如 20.17 这类早期 20.x patch。处理升级到20.19/22.12/24后重装 CLI 或项目依赖。现象配了.env但模型配置不生效。原因.env必须放在 CLI 的运行目录下与 YAML 所在目录无关且默认不覆盖已有的全局同名变量。处理确认文件位置去掉export前缀需要覆盖时用--dotenv-override排查用--dotenv-debug。现象aiTap偶尔点错相邻元素。原因目标元素视觉特征不明显单轮定位置信度不够。处理给该次调用加deepLocate: true或在提示词里补充位置线索“右上角的购物车图标”。上手进阶路线学完能做到的事用 Chrome 扩展 Playground 在任意网页上跑通第一条自然语言指令用 CLI YAML 完成一个带aiAssert的 Web 测试并读懂 HTML 报告在现有 Playwright/Puppeteer 项目中接入PlaywrightAgent混合使用 AI 步骤与传统断言用aiQuery把列表页数据按 schema 提取成 JSON接进监控或报表用 adb 连接 Android 真机跑通一个多步骤 App 流程脚本理解aiAct、aiTap/aiInput、aiAssert的分工会为稳定流程改用 JavaScript 编排会按任务复杂度选择性启用deepThink/deepLocate并观察延迟变化完成自托管开源多模态模型如 Ollama的接入打通私有化调用链路用aiContexts.default为项目注入统一业务背景币种、弹窗规则等减少重复提示词跟进 Midscene TestBeta框架用 YAML 描述测试意图 TypeScript Node 封装数据准备搭建可并发、可重试的 E2E 工程【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考