Midscene.js 完整指南：GUI Agent 驱动的 AI 自动化测试，从配模型到真机操作快速上手

Midscene.js 完整指南GUI Agent 驱动的 AI 自动化测试从配模型到真机操作快速上手【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene.js 是一个 GUI Agent 驱动的 E2E 测试框架——你写一句点击登录按钮它就自己看屏幕、做操作、验证结果。读完本文你能独立配好模型、在 Chrome 扩展里跑通第一条指令并把手动体验过的流程搬进项目脚本和 CI。适合刚接触 AI 自动化测试、手里有 Android 真机或本地 Chrome 的开发者。十秒速览⚡️ 只需要 4 个环境变量指定模型服务扩展设置页粘贴即可用无需 clone 任何仓库执行完的 HTML 报告默认生成在midscene_run目录每步的输入、输出、耗时都有记录失败点一翻便知网页、Android 真机、本地已登录的 Chrome 三种目标共用同一套自然语言指令Playground 里验证过的行为写进脚本不变低成本试一下扩展 4 个环境变量不用装依赖、不用写代码先在浏览器里把链路跑通。模型服务用 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接下来的操作全是鼠标动作从 Chrome 应用商店安装 Midscene 扩展浏览器右侧会出现侧边栏点侧边栏的设置图标把上面 4 个值粘进设置页保存打开任意网页在侧边栏输入一句自然语言例如点击登录按钮点运行上图是扩展的侧边栏上方配置模型中间输入指令下方实时展示每一步的 AI 定位框、截图和执行结果。怎么算成功执行完自动生成 HTML 报告截图、每步操作和断言结果都能回放且 AI 定位框准确落在目标元素上。这条路径和 SDK 走的是同一套代码实现你在侧边栏验证过的流程换到脚本里行为完全一致。怎么让 AI 操作 Android 真机想让 AI 点的不只是网页还有手机里的 App开发机接一根线就行。手机在开发者选项里打开 USB 调试有线连上电脑终端执行adb devices -l能看到设备序列号说明连接正常起 Playgroundnpx --yes midscene/android-playground在弹出的窗口里贴入 API Key 配置输入打开浏览器搜索 SU7AI 自行规划执行上图展示 Playground 接管真机后的画面左侧是 AI 逐条规划出的动作定位设置图标、进入 My device、读取版本号右侧是手机屏幕的实时镜像。怎么算成功跑完打开报告文件手机上每一次点击、滚动、断言都有截图留痕。这一步过了之后同样的指令直接交给 Android SDK 就能写进正式测试脚本。怎么复用已登录的 Chrome把测试写进项目很多用例卡在登录态上。桥接模式让本地脚本直接控制桌面 Chrome复用它的 cookies 和插件状态不用每次重新登录。项目里安装依赖midscene/web和tsx创建桥接 Agent 并打开目标页面import { AgentOverChromeBridge } from midscene/web; const agent new AgentOverChromeBridge(); await agent.connectNewTabWithUrl(https://example.com); await agent.aiAct(点击登录按钮);脚本一跑扩展会弹出确认窗点 Allow 或 Always Allow 授权桌面 Chrome 新开标签页自动执行流程你在旁边还能手动补操作——典型的人在回路上图是桥接模式下的侧边栏配置 Bridge Server 地址、查看连接日志脚本与浏览器共用同一登录态。如果走 YAML 脚本把bridgeMode设为newTabWithUrl就能接管本地 Chrome桥接模式文档有完整参数说明。执行挂了怎么定位读报告、查缓存与耗时AI 自动化最头疼的就是失败没有痕迹。Midscene 的 HTML 报告把每个 AI 步骤的输入、输出、耗时、状态单独记录配合截图回放问题步骤一眼可见。报告在哪运行产物默认在midscene_run目录报告、日志、缓存分目录存放设MIDSCENE_RUN_DIR环境变量可整体迁移路径怎么看点开 HTML 文件逐步回放 AI 决策过程和元素定位框报告里还能看到模型调用次数与每步耗时是模型响应慢还是页面加载慢数据直接给出答案缓存怎么提速给cache配置{ id: 任务名 }调试期读写模式可显著加速重复执行报告右侧的 Task Meta 面板会显示实际耗时对比上图是报告回放界面左侧步骤列表标注了每步耗时和缓存命中情况中间时间轴回放每一步的页面截图右侧汇总任务总耗时。报告生成的核心逻辑在 报告模块想深入机制从这里入手。排障手册现象 → 原因 → 处理现象原因处理adb devices只显示 unauthorized手机端没确认 USB 调试授权到手机屏幕上点一次允许 USB 调试弹窗报Cannot access a chrome-extension:// URL其他扩展与注入脚本冲突开发者工具里找到注入的扩展 ID到chrome://extensions禁用对应扩展Ollama 本地模型连接报 403默认来源限制拦截了请求设环境变量OLLAMA_ORIGINS*放开来源配了 cache 却没生成缓存文件缓存没配 id或只读模式下默认不落盘确认 cache 配了 id只读模式需手动调agent.flushCache()本地命中缓存CI 全量重算CI 工作区拿不到本地缓存把./midscene_run/cache目录提交进仓库Azure 上 GPT-5 点击位置按分辨率偏移模型坐标系与截图分辨率不匹配用screenshotShrinkFactor预先缩小截图规避配置速查遇到什么问题先调哪个参数遇到的情况先调哪个参数推荐值所有场景必配指定模型MIDSCENE_MODEL_NAME支持 UI 定位的多模态模型模型响应慢、经常等超时MIDSCENE_MODEL_TIMEOUT默认 180000180 秒可上调网络不稳偶发失败MIDSCENE_MODEL_RETRY_COUNT默认 1加到 2-3调试期重复执行太慢cache{ id: 任务名 }读写模式加速生产环境怕缓存被改写cache.strategyread-only报告/缓存想集中管理MIDSCENE_RUN_DIR自定义路径YAML 脚本要接管本地 ChromebridgeModenewTabWithUrl以上是通用推荐实际按你的环境和负载微调即可。接下来往哪走目标是 Web 测试先跑起来从 Chrome 扩展配好模型、发一条指令开始把报告里的步骤逐条核对后再迁到脚本参数改没改对报告里一目了然。目标是真机与桌面自动化先把 adb 连接修到adb devices -l稳定出现序列号再跑一遍 PlaygroundiOS、HarmonyOS 和桌面端的完整配置见 平台专属指南缓存三种策略读/写/只读的取舍见 缓存文档。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考