企业官网建设流程全解析

Midscene.js AI 视觉 UI 自动化实战指南：不写选择器也能操控任意界面

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

跑 E2E 测试时，最先劝退你的往往是失效的选择器：一处 CSS 类名改动，旧用例就全挂了。Midscene.js 是一款面向 E2E 测试的 GUI Agent，它凭截图"看懂"界面，再用自然语言驱动 UI 自动化测试，让你不必编写和维护任何选择器。

🧭 一句话认识它

Midscene.js 是由多模态模型（能"看懂"图片的大模型）驱动的跨平台 UI 自动化框架，核心卖点有三个：

• 纯视觉、零选择器：元素定位只依赖截图，纯图标按钮、canvas 内容也能找到
• 跨平台、同一套 API：网页、Android、iOS、HarmonyOS、桌面应用通用
• 多种写法：JS/TS SDK、YAML 脚本、零代码的 Chrome 扩展，任选其一

🧩 核心能力拆解

🎯 自然语言执行任务：aiAct

给aiAct一句自然语言目标，它会观察界面、规划步骤、定位元素并执行，直到目标完成。类似把任务交给同事，具体路径由对方自行判断：

await agent.aiAct('搜索无线耳机，将第一件商品加入购物车，并确认购物车数量变为 1');

单步且明确的操作，用aiTap（点击）、aiInput（输入）这类即时交互 API，开销比aiAct小：

await agent.aiTap('购物车中的结账按钮');

📊 结构化数据提取：aiQuery

aiQuery只观察界面，不执行操作，按你指定的结构返回数据，适合把页面信息转成 JSON：

const items = await agent.aiQuery( '页面中的商品，{name: string, price: number}[]' ); // 例如：[{ name: '无线耳机', price: 99.9 }]

✅ 视觉断言：aiAssert

aiAssert校验的是"用户真正看到的画面"。条件成立则正常结束，不成立会抛出错误并附上模型给出的原因。颜色、高亮、布局都能断言，而不只是判断 DOM 节点是否存在。

📱 一套 API 覆盖全平台

同一句aiAct，既能在网页里跑，也能跑在 USB 连接的 Android 设备、iOS 真机与桌面应用上。下面是 Android 端的控制界面：

🚀 从零跑起来

1. 安装依赖：npm install @midscene/web。
2. 配置模型：需要一个具备 UI 定位能力的多模态模型，以豆包为例（千问、GLM、Gemini 等均可，列表见模型配置）：

export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628" export MIDSCENE_MODEL_FAMILY="doubao-seed"

3. 最小脚本：存为demo.ts。Playwright 是微软开源的浏览器自动化库，这里用它启动浏览器，把页面交给 Agent：

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('Type "Headphones" in the search box, hit Enter'); const items = await agent.aiQuery( '{itemTitle: string, price: number}[], find items and prices' ); console.log(items); await browser.close();

4. 运行与查看结果：执行npx tsx demo.ts。命令行会打印抓取到的商品；同时midscene_run目录生成一个 HTML 报告，逐步展示截图、耗时与成败。

🏗️ 设计与模块

仓库按"核心引擎 + 平台适配器"划分，全部 MIT 协议开源：

各平台执行链路一致：Agent 收到自然语言目标 → 截图 → 发给模型 → 模型返回元素坐标 → 对应适配器执行动作。

💡 场景实操

场景一：电商价格巡检背景：每天早上要确认核心商品价格没变。操作：用aiAct进入商品搜索，再用下面的代码取价并断言：

const price = await agent.aiNumber('第一件商品的价格是多少？'); await agent.aiAssert(`第一件商品价格应为 ${expected} 元`);

产出：命令行输出结构化 JSON，可直接写入监控表，价格异常时断言会直接失败并留痕。

场景二：Android 发版冒烟测试背景：每次发版前验证"打开应用 → 进入设置 → 查看版本号"。操作：USB 连接手机并开启 USB 调试，创建 Android 设备 Agent，调用的仍是aiAct/aiQuery这套 API。产出：版本号返回命令行，报告里留存每一步截图。

🛠️ 上手建议与常见疑问

避坑经验：

• 单步操作用即时 API：aiAct每步都要重新规划，时间和 token 开销更高；固定动作用aiTap、aiInput。
• 先在扩展里试指令：Chrome 扩展是零代码 Playground，验证效果后再搬进 SDK。
• 模型定位能力是关键：选官方文档推荐的、UI 定位能力强的模型，能显著减少定位漂移。

问：断网能用吗？ 答：需要调用模型服务。自部署 UI-TARS、Qwen-VL 等开源模型后，可在全内网环境运行。

问：会向模型发送哪些数据？ 答：默认只发送页面截图；aiQuery等传入domIncluded: true时才会附带 DOM 信息，详见数据隐私。

问：元素定位不稳定怎么办？ 答：在对应调用上开启deepLocate（多轮深度定位），小尺寸或易混淆的元素会更稳。

Midscene.js 适合测试工程师、QA 以及想自动化跨平台界面的开发者。下一步：装好 Chrome 扩展跑通第一条自然语言指令，再把它搬进 Playwright 测试。

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