Midscene 自然语言 UI 自动化测试快速上手-育师

Midscene 自然语言 UI 自动化测试快速上手

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

Midscene 是一个开源的 GUI Agent，靠视觉 AI 完成 Web、移动端和桌面的 UI 自动化测试与界面操作。你不用写任何选择器，用自然语言就能让程序完成点击、断言和数据提取。适合测试工程师、前端开发，以及不写代码但想自动化重复点击的人。

你实际会在哪些场景需要它

这节说清楚三件事：什么时候值得引入 Midscene。

界面里全是图标按钮和 canvas。结算按钮只有图标没有文字，游戏画面画在 canvas 上。传统框架要翻 DOM 找唯一标识，Midscene 只看截图，按外观和位置找控件。Android、iOS、HarmonyOS 这类原生应用也一样能操作，不用换工具。

页面经常改版。前端一重构，选择器脚本就成片失效。视觉方案不依赖 DOM 结构，屏幕长得一样，脚本就不需要动。

要验证的是"用户看到什么"。DOM 断言只能证明元素存在，证明不了它显示得对不对。Midscene 像人一样看屏幕，能判断颜色、高亮、布局、报错提示的位置。

三条上手路径：零代码、低代码、深度定制

按你愿意写多少代码来选。

先体验：Chrome 扩展的零代码路线

适合你：一行代码都不想写，只想先看效果。从哪步开始：在 Chrome 网上应用店搜到 Midscene 装上，打开任意网页，在右侧边栏输入"点击登录按钮"这类指令直接运行。

扩展和@midscene/web包共享同一套核心能力。你在边栏里试过的指令，后面可以原样搬进代码里。

Chrome 扩展的右侧边栏，可直接试验动作、数据提取和视觉断言

再写脚本：Bridge 桥接模式的低代码路线

适合你：想从终端控制浏览器，还要复用浏览器里已登录的状态。从哪步开始：装上扩展并打开桥接开关，在终端写几行脚本附着到当前标签页。因为它就是你本机的真实浏览器，cookies、插件、登录状态都还在，脚本跑一半你还可以手动接管。具体做法见 bridge-mode.mdx。

桥接模式把本地脚本连上桌面浏览器，扩展面板里能看到监听状态

做成项目：SDK 与 YAML 的深度定制路线

适合你：要把自动化放进测试工程和持续集成。从哪步开始：先选集成方式。已经在用 Playwright 的话，把现有的page包一层PlaywrightAgent就获得了视觉能力；只想跑简单流程，就写.yaml脚本用命令直接执行；规模大了再上 Midscene Test（Beta），它把声明式流程和可编程 Node 分开，API 调用、数据准备、清理都能封装成可复用节点。

5 分钟跑通第一个示例

这节一步步带你跑一个能控制浏览器的桥接脚本。

第一步，装依赖。

# 安装 Web 包和 tsx 运行时 npm install @midscene/web tsx --save-dev

第二步，配置模型。Midscene 靠多模态模型读截图做决策，需要把模型服务写进环境变量（以豆包为例，key 换成你自己的）：

# 模型服务配置，替换成你自己的 API Key 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"

第三步，写脚本。在扩展里打开桥接开关，把下面内容存成demo.ts：

// 引入桥接模式 Agent import { AgentOverChromeBridge } from '@midscene/web/bridge-mode'; const agent = new AgentOverChromeBridge(); // 创建 Agent await agent.connectCurrentTab(); // 附着到当前激活的标签页 await agent.aiAct('输入 Midscene.js 并按回车搜索'); // 执行自然语言指令

第四步，运行并观察。

# 运行脚本，扩展会弹确认框，点允许即可 npx tsx demo.ts

你会看到浏览器搜索框自己被打上字、完成搜索。运行结束后会生成一份 HTML 报告，每步的截图、操作和结果都在里面，点开后逐张看即可。

它能帮你干的事

挑三个最常见的用法。

1. 同一功能跨平台回归。同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS 和桌面，流程逻辑不用按平台重写。在 Android Playground 里输入"打开设置查看系统版本"，左侧实时投屏，右侧逐步执行：

Android Playground 左侧投屏、右侧逐步操作，与 Web 端使用同一套 API

// 同一条指令，Web 页面和安卓设备上都能跑 await agent.aiAct('打开设置，查看当前系统版本');

2. 把页面变成结构化数据。aiQuery让你用自然语言加类型描述提取数据，直接返回 JSON 数组，适合盯价格、抓列表、整理表单内容：

// 提取商品名称和价格，返回 {name, price} 数组 const items = await agent.aiQuery('页面中的商品，{name: string, price: number}[]');

3. 断言视觉结果。aiAssert检查"预期外观是否出现"，成立就继续，不成立就抛错并记录原因。适合验证选中高亮、报错提示、canvas 画出来的内容：

// 断言不通过时会抛错，错误里带模型给出的原因 await agent.aiAssert('选中的套餐带有蓝色边框和勾选标记');

和现有工具链怎么搭配

这节只讲搭配思路，不贴完整配置。

Playwright：把已有的page包进PlaywrightAgent，aiAct和aiAssert就能用，传统expect与视觉断言可以写在同一个用例里。
Puppeteer：思路一致，同样包住现有 page 对象。
YAML 脚本：流程写在.yaml文件里，用midscene命令直接跑，适合不想维护测试框架的简单流程。
Midscene Test（Beta）：YAML 写流程，TypeScript Node 写 API 调用和数据准备，一个退款用例可以"API 建单 + UI 退款 + 结果校验"串起来。
AI 编程工具：装上 Midscene Skills，你常用的 AI 编码 Agent 也能操作界面，帮你一起写用例。

更多细节读 basics.mdx 和 quick-start.mdx。

避坑与实践经验

以下几条都是实际会踩的坑。

选模型要看它有没有 UI 定位能力，也就是能根据截图指出元素在哪个位置。Qwen、豆包、GLM、UI-TARS、Gemini 等主流多模态模型都在支持列表里，拿不准就先用扩展的 Playground 试一条指令。
桥接模式下，模型配置要写在终端环境变量里，不是浏览器侧。不少人漏了这一步，脚本跑起来却报没有模型。
扩展报Cannot access a chrome-extension:// URL of different extension，通常是别的扩展往页面里注入了脚本。去chrome://extensions禁用冲突的那个，刷新重试。
本地 Ollama 模型报 403，把环境变量OLLAMA_ORIGINS="*"设上，允许扩展访问。
单步操作用aiTap、aiInput，多步或有条件分支的流程才用aiAct。aiAct 会持续重新规划，更费时间也更费 token。
桥接脚本要上传本地文件时，先在扩展详情页打开"允许访问文件网址"，再重新连接。