Midscene.js：让 AI 像人一样"看懂"界面来做 E2E 测试

一个真实的痛点场景

想象一下周二的下午，版本上线前两小时，你的前端同事发来一条消息："购物车页面的删除按钮样式改了，测试全挂了。"你打开 CI 控制台，287 个端到端用例红了 64 个。翻开代码，失败原因清一色是 expect(locator('.cart-item-remove')).toBeVisible() —— 选择器失效了。

这就是过去十年 UI 自动化测试的核心矛盾：测试脚本需要"内部知识"才能操作界面，而界面恰恰是变化最频繁的部分。工程师花大量时间维护 CSS 选择器、data-testid 属性和自定义等待逻辑，测试的维护成本甚至超过了它捕获缺陷的价值。

Midscene.js 试图换一条路：不读 DOM，直接看截图。

项目背景与来路

Midscene.js 由字节跳动 Web 基础设施团队（web-infra-dev）开源，2024 年 7 月创建仓库，核心作者为 Xiao Zhou、Tao Yu、YiBing Lin。团队同时维护着 Rspack、Rsbuild、Rslib 等一系列前端基础设施工具，Midscene 是他们在 AI 时代向"质量保障"纵深延伸的一步。

项目定位一句话说得清：See interfaces like a human. E2E testing in natural language.（像人一样看界面，用自然语言做端到端测试）。

截至 2026 年 11 月，项目已积累 15491 星、1215 个 fork、90 位贡献者，最新版本 v1.17.5（2026-11-02 发布），仓库文件数 3014，代码以 TypeScript 为主（1200 万字节），文档侧有 125 篇 MDX 教程。

类比：给机器人装上眼睛

传统 UI 自动化像是一个背下了地图的盲人导航员——它知道"第几个路口左转"，但路牌换了、车道改了，它就迷路了。

Midscene 更像给机器人装上了一双眼睛和一个能读懂界面的视觉模型：它不认识你的按钮叫什么 id，但它能"看出"屏幕上那个红色圆形删除图标在右下角，然后直接点上去。定位依据从 DOM 结构和选择器，变成了像素 + 位置 + 语义理解。

核心功能与技术细节

1. 三段式工作流：看、动、验

Midscene 的执行模型非常清晰：Observe（读截图）→ Act（点击/输入/滚动）→ Verify（校验用户实际看到的结果）。API 上对应 aiAct、aiWaitFor、aiAssert，其中 aiAct 具备自主重规划能力，可根据最新界面状态循环思考直到目标达成。

2. 一套 API 覆盖六大平台

这是项目最有工程价值的设计。因为视觉定位不依赖渲染技术栈，只要平台能提供"截图 + 操作"两个能力，同一套 Agent API 就能复用：

Midscene Test（@midscene/test）则是另建的一层自然语言测试框架：用 YAML 描述用例和断言，需要精确控制的逻辑写成 TypeScript Node 复用，还能导出 Node Spec 给 AI 智能体读，让人和 AI 共同维护用例。框架层面提供了生命周期钩子、超时重试、并发隔离和步骤级报告等成熟能力。

3. 成本控制是核心竞争力

Midscene 只把截图而非完整 DOM 树送进模型，这一点决定了它的账单。官方公布的 AppControlBench 评测中，使用 Doubao Seed 2.1 Turbo 完成 60 个任务、通过 58 个，总模型成本仅 0.59 美元；近期接入的 Jev 1.4 在一个拼图游戏用例中平均每次模型调用耗时约 393ms、成本约 0.000211 美元。

4. 可视化调试报告

每次执行都会生成 HTML 报告，记录截图、元素定位坐标、AI 决策过程、动作与断言结果，支持回放。这对排查"AI 到底为什么点了那里"这类问题是刚需。

上手门槛

框架以 npm 包形式分发（@midscene/web、@midscene/test、@midscene/core 等），要求 Node.js 18+ 与 pnpm。最低成本的体验路径是 Chrome 扩展或 Playground（npx --yes @midscene/android-playground 一类命令即可拉起），不需要写代码。

真做工程落地则需要三样东西：Node 环境、被测应用或设备（浏览器 / 手机 / 远程桌面）、一个具备 UI 定位能力的多模态模型 API Key（GPT、Qwen、Doubao Seed、DeepSeek、Gemini、Kimi、UI-TARS 均支持，开源模型可自托管）。仓库本身未提供 Dockerfile 或 docker-compose，部署形态是 npm 包 + CLI，不是容器化交付。

争议与局限

需要客观指出的是几处真实短板：

• 稳定性依赖模型能力。视觉定位不是确定性的，同一份脚本在不同模型、不同版本下行为可能有差异，官方也不否认这一点。对于要求严格可重复的回归测试，纯视觉方案的 flaky 风险高于选择器方案。
• Midscene Test 仍是 Beta。官方在变更日志中明确其协议与 API 处于 Beta 状态，并将逐步替代旧的 YAML 自动化方案。
• 成本与延迟不可忽视。截图走模型意味着每个动作都有 API 往返，Jev 方案平均每次调用 393ms，任务链路长时延迟和费用都会累积。
• 生态依赖外部项目。ADB 通道、WebDriverAgent、libnut 等能力都建立在第三方项目之上，上游变更会传导进来。

行业意义

Midscene 代表的趋势可以概括为：GUI 智能体从"能操作"走向"能验收"。此前 computer-use 类模型主要展示的是"点得动"，而 E2E 测试要求的是"点得准且能判定对错"，后者是更高难度的工程问题。

从数据看，这个方向被持续加注：AndroidWorld 通过率 93.1%（Gemini-3.5-Flash）、MobileWorld 78.6%（Gemini-3.6-Flash）、AppControlBench 96.7%（Doubao Seed 2.1 Turbo）。项目在 2026 年被 GitHub Trending 收录，社区还衍生出 Python/Java SDK、midscene-pc 等扩展实现。

对团队的实际意义在于：如果你的产品面临"UI 迭代快、E2E 维护重"的典型困境，Midscene 值得作为试点引入一条自然语言用例，先从非核心链路验证稳定性与成本，再决定是否扩大范围。