企业官网建设流程全解析

Midscene.js 完整指南：用自然语言写 Web 与移动端的 E2E 测试

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

Midscene.js 是一个面向 E2E 测试的开源 GUI Agent（GUI 即图形界面，Agent 指能自主规划并执行操作的智能体）：它用截图驱动多模态模型去理解和操作界面。你用自然语言描述任务，它就能在 Web、Android、iOS、鸿蒙和桌面上做 UI 自动化。

它到底能干什么

Midscene.js 是一个视觉驱动的 UI 测试与自动化 SDK。它不依赖 DOM 结构或选择器，而是基于截图理解界面，核心能力有三点：

• 自然语言操作界面：aiAct接收"搜索耳机，把第一个加入购物车"这样的目标，Agent 自己规划步骤、定位元素并执行完整个流程。
• 一套 API 跨平台：Web、Android、iOS、HarmonyOS、桌面端使用同一组aiAct、aiQuery、aiAssert等 API，脚本基本可迁移。
• 断言用户真正看到的内容：颜色、高亮、布局、渲染状态都可以直接断言，而不只是"某个 DOM 节点存在与否"。

10 分钟跑通第一次 Midscene.js 自然语言指令

最省事的入口是 Chrome 扩展（官方称 Playground），不需要初始化项目。

第 1 步：装扩展。从 Chrome Web Store 安装 Midscene 扩展，打开后浏览器右侧出现侧边栏。

第 2 步：配模型。准备一个具备 UI 定位能力的多模态模型，把配置粘贴到扩展设置里。以阿里云 Qwen 为例：

export MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" export MIDSCENE_MODEL_API_KEY="your-api-key" export MIDSCENE_MODEL_NAME="qwen3.7-plus" export MIDSCENE_MODEL_FAMILY="qwen3"

仓库文档中列出的可用模型包括 Qwen、Doubao-Seed、GLM、Gemini、UI-TARS 等，也支持自托管开源模型。

第 3 步：输入自然语言指令。打开任意页面，在侧边栏输入三类指令之一：

• 操作：Click the login button
• 提取数据：Products on the page, {name: string, price: number}[]
• 检查界面：A navigation bar appears at the top of the page

执行后，模型完成操作或返回结果，运行过程会以报告形式逐步呈现。

功能特写 🎯

桥接模式：让本地脚本控制你"正在使用"的浏览器

解决什么问题：自动化启动的浏览器没有你的 cookies 和登录态，测不了需要登录的场景。能做到什么：本地 Node.js 脚本直连桌面版 Chrome，复用全部 cookies、插件和页面状态，属于典型的"人在回路"（man-in-the-loop）用法。怎么做到：脚本发起连接时扩展弹出确认框，点 Allow 后，脚本里用的还是同一套 Agent API：

import { AgentOverChromeBridge } from "@midscene/web/bridge-mode"; const agent = new AgentOverChromeBridge(); await agent.connectNewTabWithUrl("https://www.bing.com"); await agent.aiAct('type "AI 101" and hit Enter');

缓存机制：把重复的 AI 调用省下来

解决什么问题：同一条指令反复执行时每次都调模型，又慢又贵。能做到什么：Midscene 以 prompt 为 key 缓存 AI 规划步骤，Web 端还会缓存元素 XPath。官方文档给出的真实案例中，一次任务执行时间从 51 秒降到 28 秒。怎么做到：创建 Agent 时一行配置，缓存文件落在./midscene_run/cache：

const agent = new PuppeteerAgent(page, { cache: { id: "my-cache-id" }, // 默认 read-write 模式 });

两个边界要注意：aiQuery、aiAssert等查询类结果从不缓存（保证实时性）；XPath 定位缓存对 Canvas、跨域 iframe、关闭模式的 Shadow DOM、WebGL 不可用，缓存失效时会自动回退到 AI 定位，不需要你手动兜底。

一个真实场景：三行 YAML 跑通搜索 E2E 测试 🧪

Midscene 自带 YAML 脚本格式和 CLI，不写一行代码。

先建.env（放在运行命令的目录下），写入模型四件套：

MIDSCENE_MODEL_BASE_URL="你的模型服务URL/v1" MIDSCENE_MODEL_API_KEY="你的API Key" MIDSCENE_MODEL_NAME="你的模型名" MIDSCENE_MODEL_FAMILY="你的模型系列"

再写bing-search.yaml：

page: url: https://www.bing.com tasks: - name: Search for weather flow: - ai: Search for "today's weather" - sleep: 3000 - aiAssert: The results show weather information

然后执行：

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

CLI 实时打印执行进度，结束后在midscene_run/report/目录生成可视化报告，逐步回放每步截图与断言结果。YAML 里还能用${变量名}引用环境变量，用 glob 批量执行一组脚本。想换平台，把page:块换成android:（配deviceId）或ios:（配wdaPort）即可，任务流写法不变。

卡住了？高频问题

1. CLI 报Unsupported Node.js version：Rspack 工具链拒绝了较旧的 Node 20 补丁版本。解法：升级到 Node.js 20.19+、22.12+ 或 24+ 后重装依赖。
2. 扩展报Cannot access a chrome-extension:// URL of different extension：通常是别的扩展向页面注入了 iframe 或 script 造成冲突。解法：在开发者工具里按扩展 ID 找到来源扩展，禁用后刷新页面。
3. Ollama 本地模型返回 403：扩展访问被 Ollama 默认来源策略拦住了。解法：设置环境变量OLLAMA_ORIGINS="*"。
4. CI 上缓存不命中：缓存文件没随仓库走。解法：把midscene_run/cache提交进仓库，并确认页面结构与缓存生成时一致。

数据与边界

仓库文档中公布的真实基准数据：

缓存案例：同一任务执行时间从 51 秒降至 28 秒。

也要清楚它不适合的场景：

• 追求单步毫秒级响应的流水线：aiAct每次执行都要调模型规划，耗时和 token 成本更高；动作确定的单步操作应改用aiTap、aiInput这类即时交互 API。
• 截图不能外发的敏感环境：Midscene 的核心输入就是截图（个别场景还会附带 DOM），需评估数据隐私或使用可自托管的开源模型。
• 要求成本绝对确定：缓存只是加速手段，DOM 变化会使其失效并回退到 AI，模型调用预算仍需保留。

下一步去哪

• 快速上手与扩展配置：apps/site/docs/en/quick-start.mdx
• Playwright 集成指南：apps/site/docs/en/integrate-with-playwright.mdx
• 缓存完整配置与 FAQ：apps/site/docs/en/caching.mdx
• 核心引擎 Agent 层源码：packages/core/src/agent/

先按上面的 Bing 搜索 YAML 在真实页面跑通一遍，再把同样的三步（配模型、写脚本、看报告）搬到你自己的测试目标上，就是最顺的上手路线。

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