为什么 Midscene.js 值得一试：从零开始的视觉 UI 自动化实战指南

为什么 Midscene.js 值得一试：从零开始的视觉 UI 自动化实战指南

【免费下载链接】midsceneAI-powered, vision-driven UI automation for every platform.项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

Midscene.js 是一款纯视觉驱动的开源 UI 自动化工具，它让自然语言直接成为测试脚本，覆盖 Web、Android、iOS、桌面等全平台。本文将从痛点场景出发，带你零基础上手这套"看截图做事"的自动化方案，并附上可复用的代码示例与避坑清单。

一个让测试同学血压飙升的周五下午

想象一下这个场景：周五下午 4 点，前端同事合并了一版"优化样式"的代码，然后你的 87 条 UI 测试用例在 CI 上瞬间红了 60 条——原因只有一个：按钮的class从btn-primary改成了btn-main。你花了两小时逐条修复选择器，却发现下一个周一还会有新的重构等着你。

这不是段子，而是所有基于 DOM 结构、无障碍树、XPath 的自动化工具共同的宿命：页面结构天生脆弱。元素一改版就失效、纯图标按钮没有语义标记、原生应用根本拿不到 DOM、跨域 iframe 够不着……更关键的是，结构化的检查永远无法回答一个问题——界面看起来真的对吗？

Midscene.js 正是冲着这些痛点来的，它给出的解题思路只有一句话：别管结构，让模型用眼睛看。

换个思路：让 AI 看截图，而不是数 DOM 节点

Midscene.js 的核心原理朴素得有点可爱：只要这块界面能截图，它就能自动化。多模态模型拿到屏幕截图后，理解你输入的自然语言指令，自己规划坐标、自己决定点哪里、输入什么，然后替你完成操作。

这意味着自动化逻辑不再依赖任何标签、id 或层级关系，而是直接对齐"人眼看到的画面"。整套工作流是这样的：

1. 你写一句自然语言指令，比如"把搜索框里的内容清空"
2. Midscene.js 截取当前屏幕画面交给多模态模型
3. 模型结合截图与指令，给出要点击或输入的精确位置
4. Agent 执行动作并再次截图验证结果，直到任务完成

就这么简单。下面这张图就是它的 Web 自动化 Playground 界面，左侧输入自然语言指令，右侧实时展示模型规划的操作点，整个过程一目了然：

Midscene.js 凭什么值得你信任：三个硬核价值

与其罗列一堆形容词，不如直接看它能解决哪些真金白银的问题：

除此之外还有三个容易被忽略的细节：

• 失败信息可回放：每次运行自动生成可视化报告，能一步步回放 AI 的思考与操作，排查问题不用靠猜
• 两种测试风格：可以让 AI 自主规划完成整个任务，也可以把复杂逻辑拆成多步工作流，兼顾灵活与稳定
• 生态友好：能嵌进 Playwright、Puppeteer 等现有测试框架，也能通过 MCP 接入更多工具链

零代码上手：Chrome 扩展三步走

你可能会问："听起来不错，但我不想一上来就写代码怎么办？" 好消息是，Midscene.js 提供了一个零代码入口——Chrome 扩展。它本质上是一个交互式 Playground：输入指令、立即看结果、随手调试，全程不用碰命令行。

简单三步就能玩起来：

1. 在 Chrome 应用商店安装 Midscene 扩展，打开面板（可能被折叠在扩展图标里）
2. 点击齿轮图标，粘贴你的多模态模型配置（支持 OpenAI、Qwen、豆包、GLM、Gemini 等多种服务商）
3. 打开任意网页，输入一条操作指令或断言，比如"点击搜索按钮并输入 Midscene.js"，看着它替你干活

扩展与@midscene/webSDK 共用同一套核心，所以你在面板里验证过没问题的能力，写成脚本后的表现完全一致——这给了新手一条平滑的学习曲线：

写脚本同样简单：5 分钟跑通第一个自动化

如果你更习惯用代码说话，Midscene.js 的 JavaScript SDK 上手成本也低得惊人。以浏览器自动化为例，只需四步：装依赖、配环境变量、写脚本、运行。下面这段示例实现了"打开 eBay → 搜索耳机 → 提取商品列表 → 断言页面状态"的完整链路，每一步都是大白话：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; const browser = await chromium.launch({ headless: false }); const page = await browser.newPage(); await page.goto('https://www.ebay.com'); const agent = new PlaywrightAgent(page); // 自然语言执行操作 await agent.aiAct('在搜索框输入 "Headphones"，然后回车'); await agent.aiWaitFor('列表中至少出现一个耳机商品'); // 提取结构化数据 const items = await agent.aiQuery( '{ title: string, price: number }[], 列表中的耳机商品', ); // 自然语言断言 await agent.aiAssert('页面左侧有一个分类筛选栏');

运行后控制台会打印报告文件路径，在浏览器里打开这个 HTML 就能逐步回放每一次操作。除了直接嵌入脚本，Midscene.js 还支持把流程写成 YAML 文件，配合 CLI 批处理 在 CI 里一键执行，管理团队级测试资产非常方便。

认识三个核心指令：说、查、断

所有 Midscene.js 的自动化能力，本质上是几个高频 API 的组合，你只需要记住这三个：

• aiAct：让 AI 执行动作，比如点击、输入、滑动、回车，支持把多个动作串成一句话
• aiQuery：从界面提取结构化数据，可以直接返回对象数组，方便后续断言或传给其他系统
• aiAssert：验证页面状态，返回 true / false，检查的是"视觉上确实如此"而不是"DOM 里有没有"

配合aiWaitFor（等待某个视觉条件出现）、aiTap、aiBoolean等辅助方法，你就能组合出非常接近"人肉测试"的复杂流程。如果你希望 AI 完全自主决策，还可以用aiAct一次性下达多步骤任务，让模型自己规划执行顺序，适合探索性测试和冒烟场景。

从浏览器到手机再到桌面：一张截图走天下

Midscene.js 最有杀伤力的一点，是跨平台的 API 一致性。只要界面能截图，它就能工作，而每个平台早已有成熟的技术底座：

• Web：支持 Playwright、Puppeteer，以及桥接模式直接控制桌面 Chrome（见上方配图）
• Android：通过 ADB 连接设备，无需 root，底层复用 scrcpy 画面传输
• iOS：基于 WebDriverAgent 驱动，iPhone、iPad 皆可操作
• 桌面端：Windows、macOS、Linux 原生应用与 Electron 应用全覆盖
• HarmonyOS：华为鸿蒙设备也有专属接入模块

这意味着团队可以用同一套自然语言资产覆盖所有端，不用为每个平台维护一套不同的脚本方言。以 Android 为例，下面的配图展示了从"打开设置查看安卓版本号"这样的自然语言任务，到模拟设备上一步步执行的真实效果：

每次运行都留下"案发现场"：可视化报告的价值

自动化最怕什么？怕失败之后你完全不知道 AI 当时在想什么。Midscene.js 每次运行都会生成一份可交互的 HTML 报告，包含每一步的截图、模型思考过程、操作结果与耗时。排查问题时，你不再是面对一串报错日志，而是像看回放录像一样，逐帧确认 AI 在哪个环节判断失误。这份报告还能在团队内共享，让非技术同事也能看懂自动化到底跑了些什么，沟通成本直接下降一个量级。相关实现可以参考 report 模块 与核心的 report-generator。

模型怎么选：主流多模态模型都能用

Midscene.js 在设计上刻意保持了对模型的宽容度，你不需要绑定某个特定厂商。目前官方支持 Qwen、豆包、GLM、Gemini、GPT、UI-TARS 等多个系列，配置方式统一为环境变量，切换成本几乎为零。有一点建议：日常开发调试可以用响应更快、成本更低的模型，跑正式回归时再切换定位能力更强的旗舰模型——这种"开发省钱、上线保稳"的组合策略，很多团队都在用。

新手最容易踩的三个坑

为了让你少走弯路，这里提前排雷：

1. 截图质量就是一切：画面模糊、窗口过小或弹窗遮挡都会直接影响模型判断，务必保证被测界面处于可见状态
2. 指令要够具体："检查一下页面"这种模糊指令效果很差，试试"断言页面顶部导航栏包含五个菜单项"，成功率立刻提升
3. 模型配置别贴错格式：扩展与 SDK 都接受export KEY="value"格式的环境变量，粘贴时注意别漏掉引号

现在就上手

视觉驱动的 UI 自动化不是未来概念，而是今天就能上手的工作方式。Midscene.js 已经把门槛降到了"会说话就能写测试"的程度——你可以先装个 Chrome 扩展在真实网页上玩十分钟，感受一下自然语言指挥 AI 的奇妙体验；觉得对味了，再花五分钟用 SDK 写一个属于自己的自动化脚本，亲眼看看那份能回放的报告长什么样。

前端重构不再可怕，移动端测试不再无从下手，跨平台自动化不再需要 N 套脚本。Midscene.js 的完整能力都躺在 core 核心源码 和 Web 集成模块 里，文档与示例一应俱全。别犹豫了，从打开浏览器、装好扩展、输入第一句自然语言指令开始，你的第一段视觉自动化之旅，五分钟内就能启程。🚀

【免费下载链接】midsceneAI-powered, vision-driven UI automation for every platform.项目地址: https://gitcode.com/GitHub_Trending/mid/midscene