企业官网建设流程全解析

Midscene.js：用一张截图和自然语言跑通 UI 自动化，10 分钟通过第一个测试｜测试工程师实操手册

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

Midscene.js 是一个 AI 驱动的 E2E 测试 Agent：给它截图和自然语言，它自己看懂界面、定位元素并完成操作，覆盖 Web、Android、iOS 和桌面端。本文带你走通从配置模型到跑通第一个自动化脚本的完整流程，读完后你能独立运行它并看到可视化测试报告。

选择器扛不住之后：UI 自动化的真实代价

一个典型场景：前端团队改了个 class 名，前一天的回归脚本集体挂掉。XPath 又要更新了。单个脚本修起来 5 分钟，一百个脚本修一整天。这类痛点在 SPA 和原生 App 上尤其明显：

• 动态类名、哈希后缀让选择器天生脆弱，每次发版都要巡检脚本；
• 纯图标按钮、canvas 渲染页、跨域 iframe，基于 DOM 的方案基本看不到；
• 同一条流程要在 Web、Android、iOS 各写一套脚本，维护成本随平台数翻倍。

核心思路一句话：放弃对页面结构的依赖，让模型"看"屏幕。代价是每次操作都要调模型，Midscene 用缓存和规划复用把这层成本压下来。

10 分钟跑通第一个自然语言自动化

最快路径是 Chrome 扩展，不需要建任何项目，三步就能体验交互、数据提取和界面断言。

第一步：准备环境。从 Chrome 商店安装 Midscene 扩展。如果还想跑仓库里的示例项目或 YAML 脚本，先克隆代码：

# 克隆 Midscene 仓库并安装依赖（用于本地跑示例和 YAML 脚本） git clone https://gitcode.com/GitHub_Trending/mid/midscene cd midscene && pnpm install

✅ 预期结果：pnpm install无报错，Chrome 扩展列表里能看到 Midscene。

第二步：配置模型。Midscene 需要一个具备 UI 定位能力的多模态模型，官方支持豆包 Seed、千问 Qwen、GLM、Gemini 等。以豆包 Seed 为例：

# 导出模型服务配置（扩展设置页中粘贴的是同样四项内容） 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"

⚠️ 若指令执行超时报错，先确认模型服务本身可调通，且MIDSCENE_MODEL_FAMILY与所用模型系列匹配。

✅ 预期结果：配置保存后设置页无连接错误提示。

第三步：执行第一条指令。打开任意网页，在 Midscene 侧边栏输入贴合当前页面的自然语言：

• 操作界面：点击登录按钮
• 提取数据：页面中的商品，{name: string, price: number}[]
• 检查界面：页面顶部显示导航栏

✅ 预期结果：页面自动完成操作，控制台输出报告文件路径。

第四步：验证输出。每次运行都会生成 HTML 报告，浏览器打开后能看到每一步的截图、模型决策过程和耗时。简单流程也可以用 YAML 描述：

# 一份 YAML 自动化脚本：在 Bing 搜索天气并验证结果 page: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - sleep: 3000 - name: 检查结果 flow: - aiAssert: 结果中展示了天气信息

终端用midscene命令（由仓库内置的 YAML 脚本运行器提供）执行，效果和扩展里一致。

指令效果在 Playground 里验证过后，就可以把它们搬进代码。Midscene 的核心是一个 Agent 加几组方法，边界划分得很清楚。

核心能力拆解：Agent 的 API 边界

1. 自然语言规划aiAct

传一个目标，它观察界面、规划步骤、定位执行，循环自检直到完成。适合多步骤、有分支的流程：

// aiAct 示例：完成一个加购流程，步骤由模型自行规划 await agent.aiAct('搜索耳机，把第一件商品加入购物车');

2. 视觉断言与结构化提取aiAssert/aiQuery

断言校验的是"用户实际看到的"——颜色、布局、文案，而不只是 DOM 节点存在与否；aiQuery直接从画面提取带类型的结构化数据：

// aiQuery 示例：提取商品列表，按声明的类型返回数组 const items = await agent.aiQuery<Array<{ name: string; price: number }>>( '页面中的商品，{name: string, price: number}[]', );

3. 跨平台统一 API

同一套方法可以跑在 Web（Playwright/Puppeteer）、Android（ADB）、iOS（WebDriverAgent）、HarmonyOS 和桌面端，只换 Agent 类型，脚本不用改。

4. 桥接模式：控制你本机正在用的浏览器

桥接模式让本地 Node 脚本连接桌面版 Chrome，复用已有的 cookies、插件和登录状态。需要人工介入的场景（比如验证码），脚本可以停下来等人操作完再继续：

// 桥接模式示例：本地脚本控制桌面 Chrome 完成一次搜索 import { AgentOverChromeBridge } from "@midscene/web/bridge-mode"; const agent = new AgentOverChromeBridge(); await agent.connectNewTabWithUrl("https://www.bing.com"); await agent.ai('type "AI 101" and hit Enter'); await agent.aiAssert("there are some search results"); await agent.destroy();

在 Playwright 测试用例里则注入PlaywrightAgent，写法和扩展里一样：

// Playwright 集成示例：为页面创建 Agent，测试用例里直接用自然语言 import { PlaywrightAgent } from '@midscene/web/playwright'; const agent = new PlaywrightAgent(page); await agent.aiAct('type "Headphones" in search box, hit Enter'); await agent.aiAssert('There is a category filter on the left');

这四项能力覆盖日常大部分场景，接下来要优化的只剩成本和稳定性。

进阶调优：降低模型调用成本的三个策略

视觉驱动意味着模型调用是主要开销，下面三个策略都冲着它去。

开启规划缓存 —— 适合同一流程反复回归。相同 prompt 在相似页面环境重复执行时，直接复用之前保存的规划，不再调模型；缓存失效会自动回退到 AI 重新规划，查询类结果永不缓存。

// 缓存配置：给 Agent 指定唯一 id，缓存文件存于 ./midscene_run/cache const agent = new PlaywrightAgent(page, { cache: { id: "ebay-search" }, });

预期收益：官方示例里，一个重复任务的执行耗时从约 51 秒降到约 28 秒。

按角色拆分模型 —— 适合复杂任务或成本敏感场景。规划、元素定位、界面理解三件事可以分别指定模型：MIDSCENE_PLANNING_MODEL_*配规划模型，MIDSCENE_INSIGHT_MODEL_*配理解模型。规划用更强的模型保稳定，定位用更便宜的模型压成本，各取所需。

💡 若账号开通了豆包的低延迟模式，可加MIDSCENE_MODEL_EXTRA_BODY_JSON={"service_tier":"fast"}，模型响应速度大约能提升 30%–50%。

深度规划与深度定位deepThink/deepLocate—— 适合疑难任务。长流程加deepThink强化任务拆解，小元素、易混淆元素加deepLocate提高定位精度。代价是多花模型调用和延迟，建议只在关键步骤开。

模型选对、缓存开上，就可以把完整的回归套件跑起来了。至于你的场景是否真的适合，看下面的判断。

快速决策指南：该用它还是不用它

• 该用：界面改版频繁的 UI 流程、DOM 里看不见的元素（canvas、图标按钮、跨域 iframe），或想用一套脚本覆盖 Web 和移动端；
• 要权衡：超高频、对单步延迟极度敏感的场景，纯视觉方案有固有延迟和调用成本；不碰界面的纯数据抓取，直接读 DOM 更划算；
• 下一步：读仓库里的 YAML 脚本运行器与 Playwright 集成文档，再按需扩展到 Android/iOS 平台。

Midscene 是开源项目，跑通之后如果踩到坑，欢迎去社区提问或者提 Issue，一起把它磨得更顺手。

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