企业官网建设流程全解析

Midscene.js 零门槛上手指南：用 3 个真实任务玩转 AI 视觉自动化测试

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

如果你经历过"为选择器打工"的夜晚——前端改了个 class 名，整条测试用例就报废——那 Midscene.js 值得你花 5 分钟了解。它是一款面向 E2E 测试的 GUI Agent，用 AI 视觉自动化测试的思路重写了 UI 自动化：不依赖 DOM 与选择器，只凭截图让 AI 理解界面、用自然语言执行操作。本文会用 3 个贴近真实工作的任务，带你从零跑通全流程。

先搞懂一件事：为什么自动化总在"修选择器"

传统 UI 自动化大多建立在"读页面结构"之上：要么解析 DOM，要么爬无障碍树，再靠 CSS 选择器或 XPath 去定位元素。这套方案的脆弱点非常明显：

• 选择器是"死"的：页面一重构，#header .btn就失效，维护成本全压在测试工程师身上；
• 结构是"缺"的：纯图标按钮、自定义控件、<canvas>绘制的内容，在 DOM 里根本没有语义，工具"看不见"；
• 边界是"窄"的：原生 App、跨域 iframe 往往够不着；
• 最关键的是：结构无法回答"界面看起来对不对"——按钮位置、颜色高亮、布局错乱，这些只有人眼能判断。

Midscene.js 换了一条路：只凭截图工作。你把具备 UI 定位能力的多模态模型接进来，用自然语言描述目标，AI 观察当前界面、规划步骤、定位元素并执行。只要人眼能看到的，它就能定位。于是前面那些痛点——选择器失效、canvas、原生应用、视觉校验——被同一套机制一并解决。

这套机制对外暴露为几个简洁的 API 家族：

下面这张图是它的通用 Playground 界面：左侧输入自然语言指令，右侧是被控制的真实页面，Action / Query / Assert 三种模式一目了然。

你可能会有疑问："这些 API 到底怎么用？"别急，接下来我们用 3 个任务逐个击破。

🧪 任务一：让网页自己完成"搜索 → 加购 → 校验"

假设你在做电商测试，最频繁的回归就是"搜索商品并加入购物车"。传统写法要维护一串选择器，而 Midscene 的写法是这样：

import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; const browser = await chromium.launch({ headless: true }); const page = await browser.newPage(); await page.goto('https://www.example-shop.com'); const agent = new PlaywrightAgent(page); // 一句话完成"搜索耳机 → 加购 → 确认数量" await agent.aiAct('搜索"无线耳机"，把第一件商品加入购物车，并确认购物车数量变为 1'); // 提取结构化数据：返回商品名与价格组成的数组 const items = await agent.aiQuery<Array<{ name: string; price: number }>>( '列出购物车中的商品，{name: string, price: number}[]', ); // 校验界面：断言购物车小计金额存在 await agent.aiAssert('页面显示购物车小计金额');

环境前提：Node.js 20.19+，以及一个支持 UI 定位的多模态模型 API Key。安装依赖只需一条命令：

npm i @midscene/web playwright --save-dev

这段代码里，aiAct是最"聪明"的一个：它会自主规划多步动作，途中不断重新观察界面，遇到弹窗也能绕过去；aiQuery帮你把页面信息变成可直接断言的 JSON 数据；aiAssert负责"验收"——条件不满足时直接抛错，让测试真正起到拦截作用。

小提示：如果连项目都不想搭，可以先安装 Chrome 扩展体验。打开任意网页，在侧边栏输入"点击登录按钮"这类指令就能看到效果；验证通过后，把同样的指令迁移到上面的 Agent 代码里，完全无缝衔接。

任务二：把手机 App 也交给 AI 驱动

Web 只是起点。Midscene.js 对 Android、iOS、HarmonyOS 和桌面端提供同一套视觉驱动引擎——也就是说，你在网页上学到的自然语言写法，在手机上原样复用。

以 Android 为例，你只需要一台开启 USB 调试的设备（或模拟器），通过 adb 连接后启动 Playground，就能看到下面的操作面板：右侧是实时的手机画面，左侧用自然语言描述任务，AI 会先给出规划（Planning）再逐步执行。

iOS 侧同样有对应的 Playground，通过 WebDriverAgent 驱动真机或模拟器，界面风格与操作逻辑保持一致：

更有意思的是，一份 YAML 脚本可以在不同平台间复用（详见任务三）：例如"登录 → 断言欢迎页"这种跨端用例，只需切换脚本头部的平台声明，核心步骤一字不改。

🧾 任务三：不想写代码？YAML 脚本加一行命令

对于"只是想验证某个流程通不通"的场景，维护一个完整测试工程显得太重。Midscene 为此提供了一套 YAML 脚本格式：只写流程，不碰框架。看下面这个例子，你应该马上能读懂：

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

安装命令行工具后，用一条命令执行：

npm i -g @midscene/cli midscene ./weather-search.yaml

模型信息通过.env文件配置即可，全程不需要写任何代码：

MIDSCENE_MODEL_BASE_URL="https://你的模型服务地址/v1" MIDSCENE_MODEL_API_KEY="你的 API Key" MIDSCENE_MODEL_NAME="你的模型名称"

命令执行过程中会实时打印进度，结束后自动生成可视化报告——每个步骤的截图、AI 的思考过程、提取的数据都会留存，方便回溯与团队共享。

⚡ 进阶玩法：把工具用"透"的 5 个技巧

到这里，你已经掌握了最核心的 3 个能力：网页脚本、移动端驱动、YAML 零代码流程。再分享 5 个让效率翻倍的进阶技巧：

1. 用aiWaitFor处理动态加载：页面数据是异步加载的，与其写死sleep，不如让 AI 等待条件成立。await agent.aiWaitFor('商品列表已经渲染完成', { timeout: 10000 })更稳、也更省时间。
2. 用deepThink/deepLocate提升稳定性：当目标元素很小、或页面上容易混淆的元素较多时，开启深度思考模式让模型多花一次调用拆解任务，成功率明显上升。
3. 报告即调试：执行结束后打开 HTML 报告，每个操作步骤都有截图与说明；点击 "Open in Playground" 还能把失败场景原样还原，直接在可视化界面里重新调试，省掉反复重跑的痛苦。

4. 用缓存减少重复调用：同一页面在多次运行中的 AI 分析结果可以按配置复用（策略支持 read-only / read-write / write-only），跑量级回归时能省下不少 token 和时间。
5. 用 Bridge 模式接管真实浏览器：当你需要在自己正在用的浏览器里执行自动化（比如脚本与人工操作混用），可以启动 Bridge 模式让本地 Agent 与浏览器建立连接，边看边跑。

⚠️ 新手避坑：最常见的 4 个误区

• 误区一：随便选一个模型就开跑。不是所有多模态模型都擅长 UI 定位，请选择官方文档中标注"具备 UI 定位能力"的模型（如 Qwen、GLM-4V、UI-TARS 等），否则元素定位准确率会大打折扣。
• 误区二：用单步 API 描述多步任务。在aiTap里写"如果出现弹窗先关闭，再点击结账"是无效的——单步 API 只负责定位并执行固定动作，这种带分支的流程请交给aiAct。
• 误区三：遇到 403 就怀疑工具坏了。用 Ollama 自托管模型时，需要在环境变量里设置OLLAMA_ORIGINS="*"允许扩展访问；Chrome 扩展执行失败时，也先检查是否有其他扩展注入的 iframe 造成冲突。
• 误区四：担心数据隐私而不敢用。Midscene 支持自托管的开源模型（如 UI-TARS），敏感界面完全可以跑在本地，截图数据不出内网。

尾声：下一步，从这里开始

回顾一下：我们先看懂了"为什么视觉方案能绕过选择器"，然后依次用网页脚本、移动端驱动、YAML 流程 3 个任务跑通了全流程，最后补上了进阶技巧和常见坑位。对你而言，最务实的下一步是——先装 Chrome 扩展，用一条自然语言指令完成一次真实操作，感受"说人话就能测"的体验；再挑一个你最常回归的用例，把它写成 YAML 或 Agent 脚本跑通。

想深入源码或本地部署，可以克隆仓库：git clone https://gitcode.com/GitHub_Trending/mid/midscene。仓库内apps/site/docs/zh/目录下有完整的中文文档（快速开始、YAML 脚本、各平台指南），packages/下是各平台的实现源码，apps/studio/则是一款基于 Electron 的桌面集成工具。社区的更新节奏很快，多模态模型的视觉能力每代都在变强，未来这套"看屏操作"的引擎，大概率会延伸到更多你想象不到的设备上。现在，打开你的浏览器，输入第一句话试试吧。

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