企业官网建设流程全解析

Midscene 实践指南：3 条自然语言指令跑通浏览器自动化与 E2E 测试

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

Midscene 是面向 E2E 测试的 GUI Agent 框架。通过 Chrome 扩展，你可以用自然语言执行浏览器操作、提取页面数据并做视觉断言，再借助 YAML 脚本把同样的能力扩展到批量自动化与 Android、iOS 平台。

定位：给谁用，不适合谁

Midscene 是一个视觉驱动的 GUI 自动化框架：它像人一样"看屏幕"定位元素再执行操作，不需要编写 CSS 选择器或 XPath。适合需要做 Web E2E 测试的开发者、QA，以及想用自然语言自动化重复网页操作的普通用户。不适合纯接口层测试，也不适合要求毫秒级精确或必须直接操作 DOM 的场景——它依赖截图理解界面，单次动作的耗时和费用取决于所用模型。

快速上手：3 步加载扩展

1. 克隆仓库并安装依赖：

git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene && pnpm install

2. 构建 Chrome 扩展：

cd apps/chrome-extension && pnpm run build

3. 打开chrome://extensions/，开启"开发者模式"，点击"加载已解压的扩展程序"，选择扩展目录下的dist文件夹。安装完成后，打开任意网页，浏览器右侧会出现 Midscene 侧边栏。

首次使用要在侧边栏的设置页填写一个具备 UI 定位能力的多模态模型（如 Qwen3-VL、Gemini、Doubao-Seed 系列），包括模型服务地址、API Key 和模型名称。配置项说明见仓库内的 快速开始文档。

实战演示：在商品页提取价格并验证结果

用一个真实任务走完整流程：从电商搜索结果页提取商品数据，操作页面，最后断言结果。

1. 打开目标页：在浏览器中打开任意电商网站的搜索结果页，等页面稳定加载。
2. 用 Query 提取数据：侧边栏切换到 Query 模式，输入页面中的商品，{name: string, price: number}[]，点击 Run。Midscene 会按模板返回商品名和价格的 JSON 列表。
3. 用 Action 操作页面：切回 Action 模式，输入点击第一个搜索结果，进入商品详情页。执行后页面会跳到详情页，侧边栏会展示每一步的定位框和截图。
4. 用 Assert 验证结果：切换到 Assert 模式，输入商品详情页显示商品标题和价格。断言通过即说明整条任务链跑通；失败时可直接查看失败步骤的截图。

功能地图：按三个维度理解全部功能

Midscene 的功能不必逐条记，按"做什么、在哪用、怎么确认结果"归类即可。

做什么

• aiAct：用自然语言完成一串操作（点、输、滚动），适合完整流程
• aiQuery：按模板提取结构化数据，返回 JSON
• aiAssert：视觉断言，用自然语言描述期望的界面状态并判定是否满足

在哪用

• Chrome 扩展：当前页面手动输入指令，适合验证想法
• YAML 脚本 +midsceneCLI：一条命令批量跑脚本，适合 CI 和回归
• Bridge 模式：本地终端脚本接管已登录的 Chrome，复用 cookies 和登录态
• Playground 服务：独立沙盒环境，也支持预览 Android、iOS 和桌面设备

怎么确认结果

• HTML 报告：逐步的截图、元素定位框、AI 决策过程
• JSON 输出：aiQuery的提取结果、批量运行的状态汇总
• 视频导出：报告页可将完整执行过程导出为视频

场景配方：三个具体任务

配方一：Web 应用的 E2E 回归测试

目标：把维护成本高的选择器回归用例换成自然语言描述，页面小改版时用例不易失效。

做法：把流程写成 YAML：

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

然后运行midscene ./bing-search.yaml，执行完成后生成可视化报告。多个脚本可用通配符一次匹配批量执行。

注意点：.env必须放在 CLI 的工作目录下（与 YAML 位置无关）；CLI 要求 Node.js 20.19+、22.12+ 或 24+。脚本语法详见 YAML 脚本运行器。

配方二：接管已登录的浏览器（Bridge 模式）

目标：不另起一个干净浏览器，而是直接操作你手动登录过的 Chrome，省去反复登录。

做法：保持扩展的 Bridge 模式处于监听状态（图标黄点表示监听中，绿点表示已连接），在 Node 侧安装@midscene/web和tsx，脚本里用AgentOverChromeBridge连接新标签页或附着当前标签页，tsx 脚本名运行。扩展会弹窗请求允许，点 Allow 即可。注意模型配置要写在终端环境变量里，而不是浏览器侧。

注意点：脚本需要上传本地文件时，先去chrome://extensions/给 Midscene 开启"Allow access to file URLs"，否则连接后上传会失败。

配方三：页面结构化数据提取

目标：把列表页的价格、名称等字段收集成 JSON，供后续统计或入库。

做法：Query 模式下用页面中的商品，{name: string, price: number}[]这类带类型模板运行aiQuery；脚本场景里同样调用agent.aiQuery，把返回的 JSON 写入文件或数据库。

注意点：模板中字段类型要写明确，否则返回的字段名可能不稳定；大页面建议先用"前 10 条"这类小范围指令验证模板，再放开全量提取。

Midscene 常见报错与处理

• 运行提示Cannot access a chrome-extension:// URL of different extension：其他扩展向页面注入了 iframe 或 script 造成冲突。在开发者工具中找到 URL 以chrome-extension://开头的元素，复制其中的扩展 ID，到chrome://extensions/禁用对应扩展后刷新重试。
• 本地 Ollama 模型返回 403：浏览器跨域限制。在 Ollama 所在机器设置环境变量OLLAMA_ORIGINS="*"后重启服务。
• CLI 报Unsupported Node.js version：Node 版本过低。升级到 20.19+、22.12+ 或 24+，再重新安装@midscene/cli。
• 指令运行失败或返回为空：优先检查模型配置——服务地址（注意/v1后缀）、API Key、模型名是否一致，模型是否支持多模态。
• Bridge 模式连不上：扩展默认持续监听，但首次连接必须在弹窗里点 Allow；确认窗口被关掉后重新运行脚本即可。

想再深入

• 想把扩展里验证过的指令搬进代码：看@midscene/web的 Playwright / Puppeteer 集成，直接调用aiAct、aiQuery、aiAssert。
• 想测移动端：仓库内提供 Android（adb）和 iOS（WebDriverAgent）平台文档，Agent API 与 Web 端一致。

Midscene 的核心价值是用"看屏幕"的视觉 Agent 替代选择器，让自动化随界面变化保持可用。下一步建议：在扩展里挑一个你真会重复操作的业务页面，把指令跑通，再落成第一个 YAML 脚本。

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