不想再追着选择器改：Midscene.js 让浏览器自动化只说人话

不想再追着选择器改：Midscene.js 让浏览器自动化只说人话

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

Midscene.js 是一款 AI 视觉自动化工具：它不解析 DOM、不写选择器，而是让多模态模型直接看截图，你用一句自然语言控制 UI，它就完成点击、输入、取数和断言。配合浏览器自动化（Playwright、Puppeteer 或桥接模式），以及 Android、iOS 真机，它解决的是"UI 变了脚本就挂、界面复杂脚本就写不动"的老问题。写 UI 测试的开发者、想跑通端到端流程的测试同学，都适合从这里入手。

它替你解决了什么麻烦

• 选择器追着页面改。 一个前端重构，class 名和 DOM 结构全变，AI 驱动的 UI 测试脚本一夜红屏；测试同学大半时间花在"找按钮又找不到了"上，而不是设计用例。
• 有的界面根本写不了脚本。 纯图标按钮、游戏和 Canvas 区域、跨域 iframe、原生 App，没有可用的语义标注，基于 DOM 和无障碍树的工具对它们是"瞎"的。
• 一套流程，多端各写一遍。 同一个下单流程，Web、Android、iOS 各维护一套定位逻辑，改一次需求要同步改三处。

Midscene.js 的对策是干脆不碰结构：只要界面能截屏，它就当作一张图来理解，你描述"点什么、看到什么"，剩下的交给模型。

零代码到深集成的三条上手路径

零代码体验。 装一个 Chrome 扩展，配置好模型密钥，打开任意网页，直接在扩展里输入"搜索无线耳机，点进第一个结果"，就能看它动手。Midscene.js 安装体验的门槛基本就是这两步，不写一行代码、不装依赖，适合先判断这东西适不适合你的业务。

轻量脚本（Web SDK）。 确认有效之后，Midscene.js 集成 Playwright 的成本很低：

import { chromium } from 'playwright';
import { PlaywrightAgent } from '@midscene/web/playwright';

const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto('https://www.ebay.com');
const agent = new PlaywrightAgent(page);
await agent.aiAct('在搜索框输入 Headphones，按回车');

桥接模式（bridge mode）是另一条路：脚本附着到你正在使用的桌面 Chrome，Cookie、登录态、扩展全复用，适合"必须用我这个浏览器环境"的场景。这一层适合需要数据抓取、流程串联的工程师。

设备控制。 Android 走 adb、iOS 走 WebDriverAgent 连上本地设备，API 和 Web 端完全一致，同一句 aiAct(...) 在两端通用，适合做 AI 驱动的 UI 测试的多端矩阵。桌面端（computer）也有对应支持，能跑的地方基本都覆盖。

一次真实任务是怎么跑完的

选一个最常见的场景：电商页搜索耳机并校验结果。最小脚本：

const agent = new PlaywrightAgent(page);
await agent.aiAct('在搜索框输入 Wireless Headphones，按回车');
await agent.aiWaitFor('页面出现至少一个耳机商品');
const first = await agent.aiQuery(
  '{title: string, price: number}, 第一个商品的标题和价格',
);
await agent.aiAssert('第一个商品卡片上显示的是耳机');

流程是这样的：aiAct 把这句自然语言发给模型，模型截一张屏，圈出搜索框，再规划出"输入、回车"两个动作依次下发；aiWaitFor 不依赖固定毫秒 sleep，反复检查"耳机商品出现了没有"；aiQuery 把界面内容按你给的字段结构抽出来；aiAssert 负责校验，失败就抛错。每次运行都会落一份可视化报告，执行完在浏览器里逐步回放，每一步干了什么、耗时多久、当时的截图长什么样，一目了然。

它凭什么看得懂界面

定位是纯视觉的：不看 DOM、不解析标签，只看截图。模型从画面里圈出目标区域，把点击坐标、输入内容下发给浏览器或设备执行。官方支持 Qwen3-VL、Doubao-Seed、GLM-4.6V、gemini 系列和 UI-TARS 等一批视觉定位能力强的模型，开源的也能自托管，选择面比较宽。

几个值得知道的设计：

• 缓存。 AI 的规划结果和元素定位（Web 下是 XPath）会写到 ./midscene_run/cache，相同指令再跑时优先读缓存，失效自动回退模型重算；官方文档给的例子里，执行耗时从 51 秒降到了 28 秒。
• 实用函数。 除了交互类 aiAct，还有 aiLocate() 只找不点、aiWaitFor() 等待状态出现、aiAssert() 校验界面，写用例时组合起来比裸 sleep 稳。
• 给 AI 编程工具用。 MCP 服务在 1.9.8 之后已下线，新方向是 Skills：把各平台 CLI 暴露给 Cursor、Claude Code 这类 AI 编程 Agent，让 Agent 自己调 Midscene 跑测试，人只描述验收标准。
• 代码结构。 核心引擎在 packages/core/src/，平台接入如 packages/web-integration/src/，每个平台包的 API 是薄封装，核心逻辑共用一套，改起来不玄学。

什么场景该用、什么场景别用

适合：

• 跨平台、多端同一套用例：Web/Android/iOS 一套自然语言描述通吃；
• 界面视觉复杂：Canvas、图标按钮、游戏、原生 App，结构化工具够不着的地方；
• 快速验证和探索性测试：原型阶段先跑通主流程，再决定要不要转成稳定脚本；
• 断言"用户看到的东西"：颜色、高亮、布局，这些 DOM 里查不到。

劝退：

• 高频生产流水线慎上。每一步都调多模态模型，Token 成本和调用延迟都摆在那，缓存只是缓解不是根治；核心链路的回归，经典选择器脚本往往更稳更便宜。
• 视觉定位有出错率，点错按钮、读错价格会发生，关键步骤用 aiAssert 兜底，别全信。
• 强依赖模型服务：断网或 API 挂了，流程直接停，没有本地降级方案。

把效率榨干的几个技巧

1. 按场景选模型。 简单稳定的页面配便宜快速的模型省成本，定位精度要求高的交给强模型，别一套配置打天下。
2. 开启缓存并复用。 配置里写 cache: { id: 'your-task' }，相同指令第二次起走缓存；文档示例里一次任务从 51 秒降到 28 秒，回归场景收益明显。
3. 先在 Playground 里试措辞。 指令写得不准，执行就会跑偏。用 Chrome 扩展的 Playground 交互地试"点这个按钮"的多种说法，跑通了再把措辞搬进脚本，比盲猜省时间。
4. 靠报告定位问题。 失败时别只盯日志，回放报告里每一步都有 prompt、耗时和截图，"是页面没加载完还是 AI 理解错了"看一眼就能分开。

第一次上手，从快速开始把 Chrome 扩展跑通最省事；要写脚本就看Playwright 集成指南和API 参考，YAML 脚本的写法在仓库的 apps/site/docs/zh/yaml-script-runner.mdx 里，收藏这三处基本够用到熟练。

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