Midscene.js | 5分钟把一句自然语言变成能跑的E2E测试—

Midscene.js | 5分钟把一句自然语言变成能跑的E2E测试——UI自动化不用再维护选择器

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

Midscene.js 是一个 GUI Agent for E2E Testing 框架：你用自然语言描述要做什么，它看着屏幕截图替你在 Web、Android、iOS、鸿蒙和桌面应用上完成点击、输入和断言，不用写 CSS 选择器。想象一下早上发版前的场景：过去你要手工把下单流程点一遍，页面一重构，脚本里的选择器全废；现在你只需要一句话。

一句话定位：它 = 一句自然语言指令 → 视觉模型看懂屏幕、规划并执行 → 操作完成，外加一份带截图的报告。说白了，就像给机器人装上一双眼睛：它不读 DOM，只像人一样看屏幕。

🧠 它怎么做到：先看屏幕，再动手

一条指令跑起来，内部是一条直线：

截图：Midscene 拍下当前界面；
理解与规划：多模态模型按外观和位置识别元素，把"搜耳机并把第一件加购"拆成具体步骤；
执行：把点击、输入、滚动派发到对应坐标。纯图标的按钮、canvas 画面、跨域 iframe 里的元素都不在话下；
校验：aiAssert像人工测试一样判断预期结果"可见"与否，而不只是 DOM 节点是否存在；
留痕：每步的截图、坐标、AI 决策过程写进 HTML 报告，失败时可以直接回放。

入口有三条路，先说最快的：Chrome 扩展。零代码，在任意网页上就能试自然语言指令，验证过的指令稍后可以直接搬进 Agent API。

正式写脚本则是：把 Playwright/Puppeteer 已有的page交给PlaywrightAgent，之后全程自然语言。也可以完全不写代码，用 YAML 脚本加midscene命令行直接跑流程。

⏱️ 5分钟跑通 Midscene 的第一个任务

环境要求：Node.js 20.19+、22.12+ 或 24+。

安装依赖：

npm i -D @midscene/web playwright @playwright/test tsx

配置模型：在执行目录建.env，任何有 UI 定位能力的多模态模型都行。

MIDSCENE_MODEL_BASE_URL="https://你的模型服务地址/v1" MIDSCENE_MODEL_API_KEY="你的API密钥" MIDSCENE_MODEL_NAME="你的模型名"

最小脚本demo.ts：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; import 'dotenv/config'; // 读取 .env 里的模型配置 const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://www.bing.com'); const agent = new PlaywrightAgent(page); // 把页面交给 Midscene await agent.aiAct('搜索 "今日天气"'); // 自然语言指令 await agent.aiWaitFor('结果中出现天气卡片'); // 等界面就绪 await agent.aiAssert('天气卡片显示了温度'); // 视觉断言 await browser.close();

npx tsx demo.ts

跑完终端会打印Midscene - report file updated: .../xxx.html，浏览器打开就能看到每步截图和 AI 决策过程。你刚才做的事：一段 9 行的脚本，替代了过去至少 5 行选择器加 3 行等待时间，而且页面改版后大概率一个字都不用改。

🛠️ 三个场景：它到底能帮你省什么

用"夜间全量回归"解决"发版前手工回归半天"。每次发版前人工点下单主流程这件事，可以写成一份 YAML：

page: url: https://your-store.example.com tasks: - name: 主流程回归 flow: - ai: 搜索耳机，把第一件商品加入购物车 - aiAssert: 购物车角标显示 1

midscene ./regression.yaml一条命令跑完，自动出报告。夜间定时任务十分钟，你早上只需要看报告里有没有红。

用"自然语言用例"解决"测试不会写脚本"。如果你的测试同学不熟自动化框架的语法，YAML 就是那层低门槛：做什么写成ai:步骤，业务规则写成aiAssert。产品和客服都能参与维护用例——不要求编程背景，只要求他们描述得清楚页面长什么样。

用"视觉断言"解决"看不到视觉回归"。传统手段只能验证"DOM 在不在"，验证不了"显示得对不对"。Midscene 的断言直接看画面："选中的套餐有蓝色边框和对勾""错误提示出现在邮箱输入框下方"，canvas 绘制的内容和纯图标按钮也在视野里。视觉与交互回归的风险，从"靠人眼抽查"降到"机器先过一遍"。

移动端也是同一套 API：接上 Android 真机后，同样的自然语言指令就能驱动设备，Playground 里还能手动操作、随时查看设备画面。

🔌 与现有工具链的衔接

如果你已经在用 Playwright，只需要加一个依赖和一行构造：

npm i -D @midscene/web

test('加购流程', async ({ page }) => { const agent = new PlaywrightAgent(page); await agent.aiAct('搜索耳机，把第一件加入购物车'); await agent.aiAssert('购物车角标显示 1'); });

原有 fixture、expect断言、测试运行器全都不动，只把"定位难"的那几步换成自然语言指令。

如果你想进 CI：CLI 的midscene ./script.yaml不依赖 Node 项目，流水线里加一步跑 YAML 回归、把 HTML 报告存成 artifact 即可。

⚠️ 你大概率会遇到的坑

Rspack 报Unsupported Node.js version：CLI 要求 Node 20.19+/22.12+/24+，升级 Node 后重装全局依赖。
本地 Ollama 模型报 403：设置环境变量OLLAMA_ORIGINS="*"。
Chrome 扩展报Cannot access a chrome-extension:// URL：别的扩展注入了 iframe 在打架，去chrome://extensions/按扩展 ID 禁用冲突方后刷新。
aiTap点不动，换aiAct就好了：aiTap只做单动作、不规划步骤；"如果弹了窗先关掉"这类带分支的任务请用aiAct。
.env配置"不生效"：它只从 CLI 运行目录加载，且默认不覆盖同名全局变量。