Midscene.js视觉驱动的 AI UI 自动化测试从环境配置到 CI 的完整实践【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个视觉驱动的 GUI 自动化框架只靠截图和自然语言指令即可驱动网页、Android、iOS 与桌面应用适合希望把 UI 测试从选择器维护中解放出来的开发者和测试工程师。理解 Midscene.js 的定位测试屏幕而不是 DOM传统 UI 自动化乃至部分读取 DOM 或无障碍树的 AI 测试工具都依赖页面结构。这个前提很脆弱选择器在每次重构后都可能失效只有图标、没有文字语义的按钮canvas、自定义控件、跨域 iframe 对它不可见原生 App 界面则完全不在覆盖范围内。结构还无法回答另一个问题——界面上呈现的样式是否正确。Midscene.js 的做法是元素定位只基于截图。用户能看到的它就能定位到。每个步骤用自然语言描述通过三类 API 完成工作aiAct观察界面、规划步骤、执行操作直到目标完成aiQuery从截图中提取结构化数据aiAssert断言用户实际看到的内容包括颜色、高亮、布局等渲染状态。同一套 API 覆盖浏览器、Android、iOS、HarmonyOS 和桌面端。写脚本可以用 JavaScript SDK 或 YAML 文件也可以直接在 Chrome 扩展的 Playground 里零代码体验。三步上手配置环境变量并启动 Playground配置模型环境变量Midscene 依赖具备 UI 定位能力的多模态模型官方文档列出 Qwen3.x、Doubao-Seed、GLM、Gemini、UI-TARS 等含可自部署的开源模型。以豆包 Seed 为例最小配置是这 4 个环境变量export MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 export MIDSCENE_MODEL_FAMILYdoubao-seed把your-api-key换成你自己的密钥。其他模型的配置差异见仓库内的 中文文档model-config、model-common-config 两篇。验证设备连接并启动 Android Playground在系统设置的开发者选项中开启 USB 调试若存在USB 调试安全设置一并开启用数据线连接手机。运行adb devices -l出现设备序列号即连接成功。启动 Playground无需克隆仓库、无需写代码npx --yes midscene/android-playground在 Playground 窗口点击齿轮按钮粘贴上面的模型配置并保存。然后在输入框键入一条自然语言指令例如打开设置查看 Android 版本点击 Run。你会看到设备屏幕实时预览AI 自动完成打开设置、定位版本信息的过程每一步的截图与操作说明执行结束后生成带完整时间线的报告断言失败会标出原因。Playground 与midscene/androidSDK 共享同一套实现在 Playground 验证通过的流程写成脚本后行为一致——这是官方推荐的验证路径。拆解 Midscene.js 的两个核心机制机制一仅凭截图的视觉定位原理模型接收一张截图和一句自然语言描述返回目标元素的坐标Midscene 再在该坐标执行输入事件全程不接触 DOM。例子agent.aiTap(右上角的购物车图标)。购物车图标通常没有文字、没有语义化标记DOM 方案里这类图标按钮的选择器最难维护截图方案只依据视觉特征定位按钮换色、重新布局后依然能命中。这也是它对原生 App 和 canvas 界面有效的根本原因。机制二aiAct 的观察—规划—执行循环原理aiAct不是执行固定步骤而是每一轮都重新观察当前屏幕规划下一步执行后再观察直到声明的目标达成。例子await agent.aiAct(搜索耳机将第一件商品加入购物车并确认购物车数量变为 1);这条指令包含搜索、条件判断和数量验证Agent 会在执行中持续校验购物车数量变为 1这个断言不满足会调整动作。如果页面出现意料外的弹窗还可以用setAIActContext(如果出现弹窗先关闭)补充业务上下文。两种方式的取舍操作流程明确且稳定时用aiTap、aiInput等即时交互 API 或 JavaScript 编排路径可控、token 消耗低路径不确定或页面多变时aiAct的自主规划能吸收更多变化代价是更多模型调用。实战三个场景移动端、Web 页面与 CI 集成场景一移动端 App 回归测试背景电商或内容类 App 的关键路径下单、搜索、详情每次发版都要回归。midscene/android通过 adb 连接设备核心实现在 packages/android/src/。import { AndroidAgent, AndroidDevice, getConnectedDevices } from midscene/android; const device new AndroidDevice((await getConnectedDevices())[0].udid); const agent new AndroidAgent(device); await agent.aiAct(打开懂车帝搜索 SU7 车型查看参数配置); await agent.aiAssert(页面显示了 SU7 的参数配置信息);预期产出设备按指令自动操作脚本结束生成报告记录每一步的截图、耗时和断言结果失败时可直接定位到具体步骤。场景二浏览器自动化与 Chrome 扩展背景验证网页交互或快速调试一条自然语言指令的效果。最快的方式是安装 Midscene 的 Chrome 扩展在扩展侧边栏粘贴模型配置打开任意网页输入指令即可。在扩展里验证指令效果后把同一句提示词搬进 Playwright 或 Puppeteer 脚本通过midscene/web的 Agent API 集成进现有测试套件指令在两端行为一致。场景三YAML 脚本接入 CI背景日常巡检类用例冒烟、关键路径可用性检查不需要测试框架一个 YAML 文件就够。YAML 脚本运行器的实现见 packages/cli/src/。page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息tasks下每个任务按顺序执行ai即aiAct、aiAssert等步骤名与 API 一一对应。仓库中 packages/cli/tests/midscene_scripts/local/ 的示例还展示了agent.cache配置——开启缓存后重复步骤可直接命中上次结果减少模型调用。预期产出CI 中顺序执行全部任务任一断言失败即标记失败用例并生成可视化报告供排查。排查四个高频问题设备连接与模型调用adb 无法识别 Android 设备症状adb devices输出为空。原因USB 调试未完全开启、数据线仅支持充电、adb 服务卡死。解决确认开发者选项中USB 调试和USB 调试安全设置都已开启更换数据线或 USB 端口执行adb kill-server adb start-server后重新插拔。AI 定位不到目标元素症状aiTap/aiAct超时或点错位置。原因提示词描述模糊或目标元素较小、与周围元素视觉特征接近。解决在提示词中加入视觉特征如蓝色的登录按钮、带红点角标的消息图标对细小目标启用deepLocate选项额外一次模型调用换取更精确的定位。调用本地 Ollama 模型返回 403症状Chrome 扩展或浏览器端请求 Ollama 时返回 403 错误。原因Ollama 默认限制可访问的来源站点扩展的 origin 不在白名单内。解决设置环境变量OLLAMA_ORIGINS*后重启 Ollama。Chrome 扩展报跨扩展访问错误症状执行提示Cannot access a chrome-extension:// URL of different extension。原因其他扩展向页面注入了 iframe 或 script与 Midscene 冲突。解决打开开发者工具找到 URL 以chrome-extension://开头的外来元素并记下扩展 ID在chrome://extensions/中禁用该扩展刷新页面重试。选择学习资源与下一步仓库内的资料按用途分三层入门与平台指南apps/site/docs/zh/含快速开始、模型配置、YAML 脚本运行器、Android/iOS/HarmonyOS/桌面端各平台文档核心引擎源码packages/core/src/下的 agent、ai-model、report 等目录理解模型调用、元素定位与报告生成的实现测试用例与示例packages/test/example/中的完整 YAML 样例项目。建议的下一步先用 Android 或 Chrome Playground 在真实设备/页面上跑通一条自然语言指令熟悉报告结构把验证过的指令改为aiAct/aiAssert集成进现有 Playwright 测试套件选一条冒烟路径写成 YAML 脚本接入 CI 定时执行用报告中的失败截图逐条修正提示词逐步积累关键路径的断言库。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
