企业官网建设流程全解析

Midscene.js 实战指南：零门槛用 AI 视觉自动化跑通第一个 E2E 测试

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

写 E2E 测试最崩溃的瞬间，往往不是断言失败，而是页面一改版，几十个 selector 集体失效：图标按钮没有文案、<canvas>上画出来的组件拿不到 DOM、跨域 iframe 里的元素选不到。Midscene.js 就是为了解决这类问题而生的 AI 自动化测试工具：它像一个“会看屏幕的人”，靠截图理解界面，你用自然语言描述要做什么、期望看到什么，它就规划步骤、定位元素、执行操作并校验结果，同一套 API 覆盖 Web、Android、iOS、HarmonyOS 和桌面端。

核心原理一句话：每次操作前先看一眼屏幕，把任务说给 AI 听，让 AI 决定点哪里、输什么、页面是否符合预期。这意味着你不再需要写选择器，也不用给界面加测试标注。

项目速览：这是一个“能看屏幕的测试代理”

Midscene.js 把 AI 的 GUI Agent 和一套完整的测试工具链打包在一起：用aiAct执行自然语言描述的操作流，用aiQuery从界面上提取结构化数据，用aiAssert做视觉断言，运行完自动生成带截图和 AI 决策过程的 HTML 报告。适合正在被“selector 脆弱性”折磨的测试工程师、想给 App 做自动化但不懂控件树的开发者，以及希望在现有 Playwright/Puppeteer 体系里增量引入 AI 能力的团队。

场景适配度速查表

快速上手：最短路径跑通第一个脚本

不用从零搭项目，装一个 CLI、配一个模型、写一个 YAML 就能出报告。本节给出 Web 场景的最小闭环，细节可查官方文档 快速开始 和 YAML 脚本运行器。

环境要求清单

• 🖥️ Node.js20.19+/22.12+/24+（较旧的 Node 20 patch 版本会被执行链路的工具链拒绝）
• 🔑 一个具备 UI 定位能力的多模态模型 API Key（Qwen、Doubao、GLM、Gemini、GPT 等均可，也支持自托管开源模型）
• 🌐 能访问该模型服务的网络环境

第一次跑通：CLI + 一条 YAML 命令

第一步，配置模型。在项目运行目录下创建.env（注意 dotenv 约定：不加export前缀），以豆包为例：

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

第二步，写一个bing-search.yaml，再安装 CLI 并执行：

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

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

如何确认它跑通了

终端会实时打印每一步的执行进度；命令结束后生成一份交互式 HTML 报告，打开后能看到每一步的截图、元素定位框、AI 的决策理由和aiAssert的通过情况。看到“结果显示天气信息”这一步标绿，就说明视觉断言已经生效。如果你不想写任何代码只想先体验，也可以装 Chrome 扩展版 Playground，在侧边栏直接输入自然语言指令试跑（见 快速开始）。

三个高频实战场景：从 Web 回归到 App 自动化

以下三个场景覆盖了绝大多数团队引入 Midscene.js 的动机，每个都按“何时用 / 怎么配 / 怎么验证”展开。

场景一：Web 应用的 AI 回归测试

什么时候用：现有 Playwright/Puppeteer 用例因为页面改版频繁挂掉，或者要测的表单里有大量自定义组件、弹层、canvas。

操作要点：用PlaywrightAgent接管已有的page对象即可接入现有测试框架，不需要重写用例结构。多步骤、路径不确定的任务交给aiAct；结果校验用aiAssert写“用户看到的最终样子”，例如“选中方案有蓝色边框和对勾”。完整集成方式见 Playwright 集成指南。

const agent = new PlaywrightAgent(page); await agent.aiAct('搜索耳机，筛选价格低于 100 美元的结果'); await agent.aiWaitFor('筛选后的商品列表已展示'); await agent.aiAssert('每条商品的价格都低于 $100');

如何验证生效：运行后打开 HTML 报告，逐步核对截图与断言结论；断言不成立时报告会明确给出模型判定不通过的原因，方便区分“真 bug”和“脚本写得不对”。

场景二：Android App 的免控件树测试

什么时候用：要给 App 做功能回归，但不想依赖控件树、也不想让开发团队加测试 ID；典型如地图导航、订酒店、刷信息流这类多步骤操作。

操作要点：手机开启 USB 调试并连上电脑，用adb devices拿到设备号写进 YAML，后续全部用自然语言描述流程：

android: deviceId: s4ey59 tasks: - name: 地图导航 flow: - ai: 打开地图应用 - ai: 在搜索栏输入 "杭州西湖"，然后点击搜索 - ai: 点击第一个搜索结果，进入详情页 - ai: 点击 "路线" 按钮进入路线规划页面

如何验证生效：命令执行期间adb侧可看到界面被真实驱动；结束后的报告里每个ai步骤都有对应截图，逐帧对照即可确认 App 确实走到了预期页面。想零代码先试一遍流程，可用 Android Playground 在浏览器里连真机直接发指令。

场景三：视觉断言 + 结构化数据提取

什么时候用：需要盯住页面上“看得见但选不到”的东西——价格、库存数字、选中标记、报错提示，或者要把一个列表页的内容拉成 JSON 做监控比对。

操作要点：aiQuery的提示词里直接写清数据结构和类型，返回值就是可用的 JS 对象；aiBoolean适合做布尔巡检（“登录弹窗是否可见”）；aiAssert条件不成立会直接抛错，天然适合放进 CI 当卡点：

const items = await agent.aiQuery<Array<{ name: string; price: number }>>( '购物车中的商品，{name: string, price: number}[]', ); await agent.aiAssert('购物车中有一件商品，且页面显示了小计金额');

如何验证生效：aiQuery的返回直接参与后续代码逻辑（打印、落库、比对基线），数据不对一眼可见；aiAssert在 CI 中失败即红灯，报告里能查到当时的截图证据。

实战技巧与调优：先省钱，再提速

调优的核心思路是：能确定的步骤不用 AI 规划，需要 AI 的步骤给足定位精度。两条实践建议——其一，操作流程稳定且明确的分支用 JavaScript 逐步编排（aiQuery+ 循环 +aiTap），只在路径不确定处调用aiAct，可以显著降低 token 消耗和延迟；其二，复杂任务才打开增强开关：deepThink把任务拆解、规划、定位拆成多次模型调用，提升复杂流程稳定性；deepLocate增加一次定位调用，专治目标元素小、周围干扰项多的场景。

await agent.aiAct('完成结账表单，在下单前停止', { deepThink: true, deepLocate: true, context: '如果出现地址确认弹窗，请选择默认收货地址。', });

模型选型上，README 给出的公开基准里 Midscene 在 AppControlBench 的 60 个任务总成本约 $0.59（Doubao Seed 2.1 Turbo 配置下），说明截图驱动的交互路径并没有把 DOM 树塞给模型，成本可控；团队也可以按“规划用强模型、定位用轻量模型”的组合进一步压成本。

常见坑：现象、原因与处理

• 现象：扩展里运行报Cannot access a chrome-extension:// URL of different extension。原因：其他 Chrome 扩展向页面注入了iframe或script，与 Midscene 冲突。处理：在开发者工具里找到该标签，按扩展 ID 到chrome://extensions/禁用冲突扩展后刷新页面。

• 现象：用 Ollama 自托管模型时请求返回 403。原因：Ollama 默认拒绝来自 Chrome 扩展的跨域来源。处理：启动 Ollama 时设置环境变量OLLAMA_ORIGINS="*"。

• 现象：执行 YAML 时 Rspack 报Unsupported Node.js version。原因：Node 版本过旧（例如 20.17 这类早期 20.x patch）。处理：升级到20.19+/22.12+/24+后重装 CLI 或项目依赖。

• 现象：配了.env但模型配置不生效。原因：.env必须放在 CLI 的运行目录下（与 YAML 所在目录无关），且默认不覆盖已有的全局同名变量。处理：确认文件位置，去掉export前缀；需要覆盖时用--dotenv-override，排查用--dotenv-debug。

• 现象：aiTap偶尔点错相邻元素。原因：目标元素视觉特征不明显，单轮定位置信度不够。处理：给该次调用加deepLocate: true，或在提示词里补充位置线索（“右上角的购物车图标”）。

上手进阶路线：学完能做到的事

• 用 Chrome 扩展 Playground 在任意网页上跑通第一条自然语言指令
• 用 CLI + YAML 完成一个带aiAssert的 Web 测试，并读懂 HTML 报告
• 在现有 Playwright/Puppeteer 项目中接入PlaywrightAgent，混合使用 AI 步骤与传统断言
• 用aiQuery把列表页数据按 schema 提取成 JSON，接进监控或报表
• 用 adb 连接 Android 真机，跑通一个多步骤 App 流程脚本
• 理解aiAct、aiTap/aiInput、aiAssert的分工，会为稳定流程改用 JavaScript 编排
• 会按任务复杂度选择性启用deepThink/deepLocate并观察延迟变化
• 完成自托管开源多模态模型（如 Ollama）的接入，打通私有化调用链路
• 用aiContexts.default为项目注入统一业务背景（币种、弹窗规则等），减少重复提示词
• 跟进 Midscene Test（Beta）框架：用 YAML 描述测试意图 + TypeScript Node 封装数据准备，搭建可并发、可重试的 E2E 工程

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