Midscene.js GUI Agent：AI 自动化 E2E 测试完整指南-创锋一号

Midscene.js GUI Agent：AI 自动化 E2E 测试完整指南

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

发版前还得人工把登录、下单、支付点一遍？Midscene.js 是个 GUI Agent——能看屏幕、自己点按钮的 AI 程序——驱动的 E2E 测试框架。你用自然语言描述任务和预期结果，它截图、分析、定位元素，点击、输入、滚动，再把每一步的截图和断言结果写进 HTML 报告，失败定位不用再翻日志猜。

先看到它动，再解释它

装好 Chrome 扩展后，侧边栏里输入一句"点击登录按钮"，页面就被点了；输入"提取页面里的商品和价格"，结构化数据直接返回。背后只有一件事：它拿到当前截图，交给多模态模型定位元素，再按你的指令回放操作。

模型配置就四个值，粘进扩展设置页保存：

export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628" export MIDSCENE_MODEL_FAMILY="doubao-seed"

浏览器里：扩展与已登录 Chrome 桥接

接上：扩展是 Web 的 Playground，与@midscene/web共享同一套实现，侧边栏里跑通的流程换成脚本行为完全一致。一句指令：aiAct执行、aiQuery提结构化数据、aiAssert断言，侧边栏直接输入即可。产物：跑完自动生成 HTML 报告，浏览器打开就能逐步回放。

要复用你已登录的 Chrome，走桥接模式。本地脚本接管桌面浏览器，复用 cookies、插件和页面状态，省掉重复登录，也方便人在回路里补操作：

import { AgentOverChromeBridge } from "@midscene/web/bridge-mode"; const agent = new AgentOverChromeBridge(); await agent.connectNewTabWithUrl("https://www.bing.com"); await agent.aiAct('type "AI 101" and hit Enter'); await agent.aiAssert("there are some search results");

脚本一跑，扩展弹确认窗，点Allow或Always Allow，桌面 Chrome 新开标签页自动执行。

脚本里：Node SDK 写进正式测试

接上：项目里装@midscene/web和tsx，用PlaywrightAgent(page)或PuppeteerAgent(page)拿 agent，接入你现有的测试框架和用例。一句指令：await agent.aiAct('搜索耳机并过滤 100 元以内')，配aiWaitFor等结果、aiAssert校验可见状态。产物：控制台打印report file updated: ...html，报告落在midscene_run/report下，浏览器打开即可回放。

设备里：adb 连真机操作 App

接上：开发者选项里开 USB 调试（若有"USB 调试（安全设置）"一并开），数据线连电脑，先验证连接：

adb devices -l

出现设备序列号即连接成功，手机弹出"允许 USB 调试"时点允许。一句指令：起 Android Playground，窗口里输入"打开浏览器搜索 SU7"，AI 自行规划执行：

npx --yes @midscene/android-playground

产物：手机上的每次点击、滚动、断言都有截图留痕，同样落在 HTML 报告里。

挂了怎么查：报告回放怎么读

报告里每个 AI 步骤的输入、输出、耗时、状态都单独记录，配截图回放，失败步骤一眼可见。核心逻辑在 report-generator.ts，想深挖机制从这里进。缓存命不命中、模型响应还是页面加载慢，数据直接给答案。

症状	原因	一行修法
`adb devices`只显示 unauthorized	手机没点允许	手机弹窗点一次"允许 USB 调试"
`Cannot access a chrome-extension:// URL`	别的扩展注入冲突	`chrome://extensions`禁用对应扩展
Ollama 报 403	本地模型来源被拦	设`OLLAMA_ORIGINS="*"`
配了 cache 没生成文件	只读模式没手动写	调`agent.flushCache()`

核心参数速查

参数	推荐值	什么时候才需要改它
`MIDSCENE_MODEL_NAME`	支持 UI 定位的多模态模型	换模型服务商时
`MIDSCENE_MODEL_TIMEOUT`	`180000`（默认 180 秒）	模型响应慢时上调
`MIDSCENE_MODEL_RETRY_COUNT`	`1`	网络不稳时加到 2-3
`cache`	`{ id: "任务名" }`	想加速重复执行时
`cache.strategy`	`read-only`	生产环境防缓存被改写
`MIDSCENE_RUN_DIR`	默认`midscene_run`	想把报告/缓存挪到别处时
`bridgeMode`	`newTabWithUrl`	YAML 脚本要接管本地 Chrome 时
`screenshotShrinkFactor`	默认`1`	GPT-5/Azure 点击坐标偏移时

缓存三种策略的取舍见 caching.mdx；iOS、HarmonyOS 和桌面端配置见平台指南。

下一步：从 Web 或真机先跑起来

Web 先跑：装 Chrome 扩展，配好模型，发一条aiAct，看报告确认流程对。真机先跑：修好adb devices的连接，起一遍 Android Playground，参数对不对报告里一看便知。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析