企业官网建设流程全解析

Midscene.js 完整上手指南：用自然语言驱动 E2E 自动化测试

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

回归一个搜索页时，前端重构换了 class，二十多行选择器一夜全红，你只能挨个重新定位。Midscene.js 是面向 E2E 测试的视觉驱动 GUI Agent：它看截图、听懂自然语言，你说"在搜索框输入耳机并搜索"，它自己找到搜索框、输入、点击，再校验结果。

从选择器地狱到一句话脚本：Midscene 改写了哪些日常 🧹

本节回答一个实际问题：哪些测试工作会因 Midscene 而变简单。

Web 回归不再怕前端重构。传统 Playwright 脚本把选择器写死，页面 class 一改整条用例失效，CSS 和 XPath 越攒越多。Midscene 让你用自然语言描述"页面顶部的搜索框"，它按截图的视觉特征定位元素；页面 class 全部更换，只要长相不变，脚本通常照常工作。纯图标的按钮、canvas 绘制的内容、跨域 iframe 里的元素，都不需要选择器或语义标注。

一套 API 打通 Web 与移动端。传统做法里 Android 走 UIAutomator2、iOS 走 WebDriverAgent，两套 API、两套元素描述各自维护。Midscene 在同一组 Agent API 下覆盖 Web、Android、iOS、HarmonyOS 和桌面端，YAML 脚本里把目标段从page换成android，指令本身一个字不用改。

Midscene.js 快速上手 ⚡：4 步跑通第一个 YAML 脚本

本节给你最短路径：从空环境到一条可运行、可查报告的 E2E 脚本。

1. 装 CLI。需要 Node.js 20.19+、22.12+ 或 24+，一条命令npm i -g @midscene/cli。若报 "Unsupported Node.js version"，先升级 Node。

2. 配模型。在工具运行目录创建.env，指向任一具备 UI 定位能力的多模态模型（豆包 Seed、Qwen-VL、Gemini、GPT 等）：

MIDSCENE_MODEL_BASE_URL="https://your-model-service/v1" MIDSCENE_MODEL_API_KEY="your-api-key" MIDSCENE_MODEL_NAME="your-model-name" MIDSCENE_MODEL_FAMILY="your-model-family"

注意没有export前缀，且.env必须放在工具运行目录、而非 YAML 所在目录。支持模型的完整清单见模型配置文档。

3. 写脚本。新建bing-search.yaml：

page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - sleep: 3000 - aiAssert: 结果显示天气信息

ai是aiAct的简写：一句指令即可，不用拆解"点哪个框、输什么字"。

4. 运行并看报告。执行midscene ./bing-search.yaml，终端实时打印进度，结束后在midscene_run/report/生成 HTML 报告，浏览器打开即可看到每步截图、AI 决策过程和断言结果。

报告里点不开、断言莫名失败时，先看对应步骤的截图，基本能区分是"没找到元素"还是"找到但点错"。

Midscene 核心用法：指令、数据与桥接

本节讲三个日常最高频的功能，每个都给出"价值 → 用法 → 例子"。

一句话驱动多步操作 🎯

它能帮你把"登录、进设置、改主题"这类多步流程压成一句目标，Agent 自动拆解为点击、输入、滚动，失败时自动重新规划。用法是在 task 的flow里直接写目标，例如官方 Android 示例里的- ai: 在搜索栏输入 "杭州西湖"，然后点击搜索按钮。复杂路径可拆成多句ai，每句一个检查点，报告回放时更容易定位断在哪一步。

把页面变成数据和断言 📊

aiQuery从页面直接抽结构化数据，aiAssert用视觉判断"屏幕是否长该长的样子"。传统做法要 querySelector 加 JSON.parse 抓价格、expect 断言文本；这里一句话描述结构和预期即可。- aiQuery: 搜索结果中的商品，{title: string, price: number}[]返回可直接使用的数组；- aiAssert: 界面左侧有类目筛选功能在界面不符时让任务失败，并保留失败截图。给步骤加name字段，结果会写入 JSON 输出，方便下游脚本消费。

桥接模式：脚本接管你正在用的浏览器 🌉

需要登录态、依赖浏览器插件的内网系统，无头脚本往往进不去。桥接模式通过 Chrome 扩展把本地脚本连上桌面 Chrome，复用 cookies、插件和页面状态，支持新建标签页或附着当前标签页。

YAML 的page段加一个字段，midscene命令即可驱动已有浏览器：

page: url: https://www.bing.com bridgeMode: newTabWithUrl

脚本运行时扩展会弹确认窗，点 Allow 后接管。newTabWithUrl新开标签页，currentTab附着当前页；注意userAgent、cookie等浏览器配置在桥接模式下会被忽略，因为直接复用你本机的浏览器环境。

进阶配置与常见报错排查

本节解决两件事：让脚本跑得更快更稳，以及出问题时去哪里查。

提速：缓存 + 并发 🚀

缓存会保存 AI 规划结果与元素定位，重复执行直接命中。官方示例中同一任务耗时从 51 秒降到 28 秒。YAML 里只需四行：

agent: cache: id: my-cache strategy: read-write

缓存文件在midscene_run/cache/，未命中会自动回退模型分析；完整策略（只读、只写、手动清理）见缓存文档。多个互不依赖的脚本则交给 CLI 并发：midscene './scripts/search-*.yaml' --concurrent 4 --continue-on-error --retry 2，全部参数说明在脚本运行器文档。

症状 → 排查思路 🔍

• 点击偏移、点到相邻元素：先核对MIDSCENE_MODEL_FAMILY是否配错；把提示词改成视觉描述加位置（"页面右上角的人形头像图标"），并给该步骤开deepLocate: true。
• 下拉选项点不到：原生select的选项由操作系统渲染，不会出现在截图里。先查报告截图里是否真的没有选项；Midscene 默认开启forceChromeSelectRendering强制 Chrome 渲染，若你改过配置请恢复。
• 截图超时：报错含page.screenshot: Timeout ... waiting for fonts to load时，是 Playwright 卡在字体加载，CI 和容器环境常见；export PW_TEST_SCREENSHOT_NO_FONTS_READY=1后重跑即可。
• 首次运行下载浏览器太慢：Playwright 在npm install时默认不下载浏览器，先单独执行npx playwright install --with-deps chromium，或配置镜像加速。

下一步

Midscene.js 用"截图 + 自然语言"替代"选择器 + 固定步骤"，把第一条可用 E2E 脚本的落地成本压到了半天以内。

建议接下来做三件事：

1. 用 CLI 跑一个真实页面，把报告回放流程走一遍，熟悉报告结构
2. 挑 2~3 条最高频的回归路径迁移成 YAML，替换掉最脆弱的那批选择器
3. 开启缓存与并发执行，对比耗时和模型调用次数，再决定哪些任务纳入常规调度

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