如何用 Midscene.js 视觉自动化测试，让 AI 替你"看"界面、写脚本
项目地址: https://gitcode.com/GitHub_Trending/mid/midscene 写自动化测试最折磨人的时刻，往往不是逻辑写不出来，而是刚写好没两周，前端改了个 class，所有定位全崩了。你不得不翻出几十条选择器一条条修，周而复始。Midscene.js 是一款基于视觉语言模型的开源 UI 自动化测试工具，它直接"看"屏幕截图来完成元素定位和操作，用自然语言描述步骤即可驱动测试，帮你彻底摆脱选择器维护的泥潭。本文将带你了解它的工作原理、能力边界，并给出最快上手的完整路径。
为什么传统 UI 自动化越写越痛
大部分自动化框架（包括一部分号称 AI 的工具）本质上还在依赖页面结构：DOM 树、可访问性树、XPath。这套思路有三个绕不开的硬伤：
- 结构脆弱：UI 一重构，选择器就失效，测试维护成本跟着前端开发一起水涨船高；
- 覆盖有盲区：纯图标按钮、自定义控件、
<canvas>绘制的内容，在 DOM 里"看不见"；原生 App、跨域 iframe 更是直接够不着； - 验证不到视觉：你无法断言按钮颜色对不对、弹窗是不是真的盖住了内容、布局有没有错位——因为这些只存在于"渲染之后"。
换句话说，结构驱动的测试从来都是在"猜"界面，而不是"看"界面。而人类测试员从来不看 DOM，只看屏幕。Midscene.js 想做的，就是让机器也学会这件事。
一句话理解 Midscene.js 的核心理念
只认截图，不认结构。 Midscene.js 的 UI 自动化测试完全基于屏幕截图运行：你用自然语言描述"点击搜索框并输入关键词"，多模态大模型"看"一眼截图，自己判断元素在哪、该怎么点。数据提取和页面理解需要时，也可以选择性地补充 DOM 信息，但元素定位的主路径始终是纯视觉的。
这套设计带来的收益很直接：
- 前端重构不再牵动测试代码，少维护一大堆废选择器；
- 人类肉眼能看到的界面，它都能操作，包括无语义标记的元素和原生应用；
- 可以断言"用户实际看到的样子"，比如高亮、颜色、渲染状态，而不是某个节点是否存在；
- 测试方式灵活：既能嵌入 Playwright / Vitest 等现有测试套件，也能交给 AI Agent 自主执行。
视觉驱动 vs 结构驱动：一张表看懂差距
| 对比维度 | 传统结构驱动 | Midscene.js 视觉驱动 |
|---|---|---|
| 定位依据 | DOM / 可访问性树 / XPath | 屏幕截图 + 多模态模型 |
| UI 重构影响 | 选择器失效，测试大面积返工 | 界面能看懂就能继续跑 |
| 无语义元素 | 无法识别 | 看得见即可操作 |
| 原生应用、跨域 iframe | 通常难以触及 | 截图即可覆盖 |
| 视觉断言 | 基本不支持 | 支持颜色、布局、高亮等 |
| 脚本编写方式 | 手写定位器 + 逻辑 | 自然语言描述步骤 |
对测试工程师来说，这意味着写脚本的方式从"跟浏览器结构打交道"变成了"跟产品经理说话"。
Midscene.js 能自动化哪些平台
Midscene.js 的能力边界是"只要能截图就能自动化"，一套 API 打通所有平台：
🌐 网页浏览器
支持通过 Puppeteer、Playwright 或桥接模式（Bridge Mode）连接浏览器。桥接模式特别适合本地调试：浏览器开着，终端里写代码，AI 直接操作当前打开的标签页。
📱 手机 App：Android / iOS / HarmonyOS
不用 root、不用越狱，Android 通过 ADB 连接设备，iOS 借助 WebDriverAgent，兼容华为鸿蒙设备。下面两张图分别是 Android 和 iOS 设备上的真实执行效果：AI 先规划步骤，再逐步操作手机界面。
🖥️ 桌面应用
Windows、macOS、Linux 桌面程序，包括 Electron 应用和系统级界面，都在覆盖范围内。
最快的接入方法：两条路任选
Midscene.js 特意设计了两条入门路径，按你的偏好挑一条就行：
路径一：Chrome 扩展，零代码体验
如果你不想写任何代码，先装 Midscene 的 Chrome 扩展。它相当于一个交互式游乐场：打开扩展面板、配置好 AI 模型参数，然后在任意网页上用自然语言下指令，立刻就能看到 AI 的规划、执行和结果预览。适合先验证想法、熟悉交互模式。
路径二：npm 初始化，直接写脚本
如果你要的是可重复的自动化流程，走 SDK 路线：
# 创建新项目
npm create midscene@latest
# 安装依赖
npm install
# 配置 AI 模型
export MIDSCENE_MODEL_PROVIDER=openai
export MIDSCENE_API_KEY=your_api_key
# 运行示例脚本
npm run dev
最小可运行示例：看懂一次调用
下面这段代码展示了视觉自动化测试最核心的三个 API：操作（aiAct）、查询（aiQuery）和断言（aiAssert）：
// 点击搜索框并输入关键词，然后回车搜索
await agent.aiAct('Click the search bar and type "Midscene.js tutorial"')
await agent.aiAct('Press Enter to search')
// 查询页面上的搜索结果标题
const titles = await agent.aiQuery('List all search result titles')
// 断言页面确实渲染出了结果
await agent.aiAssert('The search results are visible on the page')
白话解释：aiAct 是"让 AI 动手"，aiQuery 是"让 AI 汇报看到什么"，aiAssert 是"让 AI 判断对不对"。三句话，就把一次完整的测试流程写完了。
常见问题排查清单
模型返回异常时，按顺序检查：
- ✅ API 密钥是否正确配置，模型服务商当前是否可用；
- ✅ 网络连接是否正常，代理是否拦截了请求；
- ✅ 多模态模型是否具备较强的 UI 定位能力（官方推荐 Qwen、GLM、Gemini 等视觉模型，也支持自托管的开源模型）。
移动设备连不上时，逐项排查：
- Android：确认已开启 USB 调试，
adb devices能看到设备； - iOS：检查设备信任设置与 WebDriverAgent 运行状态；
- 鸿蒙：确认 hdc 工具与设备连接正常。
想让测试更快，可以试试：
- 适当调整截图质量，平衡速度与识别精度；
- 复用缓存，减少重复的模型调用；
- 把相关的多个操作合并成一句指令，减少交互轮次。
进阶玩法：Skills 与自定义界面
Midscene.js 不止能测标准平台。它的视觉驱动引擎可以接入任何"能出截图"的界面，配合 Midscene Skills 还能让 AI Agent（如 OpenClaw）直接控制多个平台自主执行任务。项目仓库里有大量现成示例可以参考：Web 测试案例在 packages/web-integration/tests/ai/，移动端脚本在 packages/android/demo/ 和 packages/ios/demo/，核心引擎实现位于 packages/core/。
官方文档按平台拆分得很细，建议按需取用：
- 快速开始：apps/site/docs/zh/quick-start.mdx
- API 参考：apps/site/docs/zh/api.mdx
- 各平台指南：
apps/site/docs/zh/下的 android / ios / harmonyos / desktop 分册
写在最后：让 AI 成为你的测试搭子
Midscene.js 把 UI 自动化测试从"结构驱动的脆弱工程"带向了"视觉驱动的智能协作"：你负责用自然语言描述意图，模型负责看、想、做、验。它未必取代测试工程师，但一定能帮你省下大量修选择器、补定位、写断言的时间，把精力放回真正有价值的地方——测试策略和业务逻辑本身。
现在就可以开始：装个扩展，打开任意网页说一句"点击右上角的登录按钮"，然后亲眼看看 AI 是怎么"看懂"你的界面的。马上试试，你会上瘾的。🎯
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
