Midscene.js 技术解析：面向 E2E 测试的视觉驱动 GUI Agent 与 Testing Kit

Midscene.js 技术解析：面向 E2E 测试的视觉驱动 GUI Agent 与 Testing Kit

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

Midscene（GUI Agent for E2E Testing）是一个由 AI 视觉驱动的 GUI Agent，通过同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS 与桌面端，并将自动化能力组织为可持续维护的 E2E 测试工程。本文以仓库中的 README.zh.md 为主体展开，结合 monorepo 内的核心源码（Agent 基类、Playwright 集成、Midscene Test 框架 等）印证其实际架构与调用关系。读完本文，你将掌握：如何用自然语言编写视觉驱动的 UI 测试、aiAct/aiWaitFor/aiAssert/aiQuery等 API 的底层实现机制、多平台 Agent 的工程组织方式，以及如何从仓库结构判断各能力模块的落点。

核心理念：观察屏幕、执行操作、验证结果

README 开宗明义地给出 Midscene 的设计模型：Midscene 的操作与断言都仿照人使用软件的方式——观察屏幕，根据看到的内容操作，再检查界面呈现的结果。你用自然语言描述任务和预期结果，Midscene 根据截图判断在哪里操作，以及界面是否符合预期。

这意味着测试代码里不再需要 CSS 选择器或 XPath，取而代之的是对"屏幕上应该出现什么"的自然语言描述。这一理念在源码中体现得非常直接：

• 截图是 Agent 的核心输入。基于截图的 UI 操作无需向模型发送庞大的 DOM 树，这也是其成本控制的关键（详见后文）。
• 元素定位依赖"外观 + 位置"，因此纯图标按钮、自定义控件、<canvas>和跨域 iframe 中的元素都可以被定位，无需编写选择器或添加语义化标注。
• 断言同样走视觉通道，像人工测试一样观察屏幕、判断预期结果是否呈现。

从源码结构看，这一模型集中在packages/core/src/agent/目录下：agent.ts 定义 Agent 基类及其全部 API，insight.ts 承载aiQuery/aiAssert等"感知类"能力，task-executor 负责把自然语言计划转成可执行动作。

30 秒上手：Playwright 中的视觉测试

README「如何使用」一节给出的完整示例是这样的：配置好模型，并在已有的 Playwrightpage中打开你的应用后：

import { PlaywrightAgent } from '@midscene/web/playwright'; const agent = new PlaywrightAgent(page); // 让 Agent 完成流程，再验证结果。 await agent.aiAct('搜索耳机，然后将结果筛选为价格低于 100 美元'); await agent.aiWaitFor('筛选后的搜索结果已显示'); await agent.aiAssert('搜索结果中的每件商品价格都低于 100 美元');

打开生成的 HTML 报告，即可查看截图、操作与断言结果。

对照源码，这段示例的落地路径是：@midscene/web/playwright子路径导出自 playwright/agent.ts，其中PlaywrightAgent实际来自 playwright/page-agent.ts，同时该模块还导出PlaywrightBrowserAgent（面向浏览器实例而非单页面）以及overrideAIConfig（来自@midscene/shared/env的模型配置覆盖入口）。

除了手动new PlaywrightAgent(page)，仓库还提供了与 Playwright Test 测试器原生集成的 fixture 方案：playwright/ai-fixture.ts 中的PlaywrightAiFixture会依据测试名自动生成缓存 ID 与报告文件名（见 report-filename.ts），并支持以下配置项（从 ai-fixture.ts 的参数解构可以确认）：

• forceSameTabNavigation（默认true）：强制导航留在当前标签页；
• autoFollowNewPage（默认false）：自动跟随新打开的页面；
• waitForNavigationTimeout/waitForNetworkIdleTimeout：导航与网络空闲等待超时，默认值来自 constants 中的DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT与DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT；
• cache：任务缓存策略，取值false | true | { strategy: 'read-only' | 'read-write' | 'write-only', id? }，用于命中时跳过重复的 AI 调用。

仓库内还附带了 Midscene Test 的 Web 示例工程 web-midscene，其中的 midscene.yaml 展示了框架级用例的 YAML 写法，可以作为起步参考。

GUI Agent：视觉理解与跨平台操作

从一句自然语言到一次点击

README 强调：就像人从屏幕上找到控件一样，Midscene 根据元素的外观和位置进行定位，再通过点击、输入、滚动等操作完成指令。在源码层面，这条链路可以精确追踪。以aiTap为例，agent.ts 的实现是：

async aiTap( locatePrompt: TUserPrompt, opt?: LocateOption & { fileChooserAccept?: string | string[] }, ): Promise<void> { assert(locatePrompt, 'missing locate prompt for tap'); const detailedLocateParam = buildDetailedLocateParam( locatePrompt, this.withContext('aiTap', opt), ); // 支持文件选择器场景的点击 await withFileChooser(this.interface, fileChooserAccept, async () => { await this.callActionInActionSpace('Tap', { locate: detailedLocateParam }); }); }

而所有单步动作（Tap/RightClick/DoubleClick/Hover…）最终都汇聚到 callActionInActionSpace：它把动作包装成一个PlanningAction计划，再经由taskExecutor.runPlans执行——这里分别解析default（默认视觉模型）与planning（规划模型）两类运行时，印证了 README 中"按场景组合规划模型与视觉模型"的说法。aiAct（自主多步流程）则走更长的任务规划循环（agent.ts），由规划模型逐步拆解自然语言目标。

值得注意的是aiInput同时提供了新旧两套签名（agent.ts）：推荐的新签名是aiInput(locatePrompt, { value, ... })，旧的aiInput(value, locatePrompt)已标记@deprecated。若你阅读社区旧代码时看到两种写法，原因即在于此。

一套 API，五个平台

README 声明同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS 和桌面应用。从 monorepo 结构可以逐一印证各平台包的位置：

此外 packages/web-integration/src/chrome-extension 目录承载 Chrome 插件版 Agent 的实现，对应 README「Playground」一节中从 Chrome 插件开始体验的入口。README 还指出：只要你提供截图和操作能力，就可以接入[自定义界面]（即任意能截屏、能执行点击/输入的设备都可以适配为 Agent 的运行目标）。

验证用户真正看到的效果：视觉断言

断言也采用同样的视觉方式：Midscene 像人工测试时一样观察屏幕，判断预期结果是否呈现。用自然语言描述预期外观，就能检查颜色、选中高亮、布局和视觉反馈，也适用于<canvas>绘制的内容和原生应用界面：

await agent.aiAssert('选中的套餐带有蓝色边框和勾选标记'); await agent.aiAssert('邮箱输入框下方显示了错误提示');

在源码中，aiAssert定义于 agent.ts，其"感知类"实现位于 insight.ts 与 ui-observer.ts：它们以截图（而非 DOM）为输入，让多模态模型判断自然语言描述的界面状态是否成立。aiWaitFor（agent.ts）则是对断言的轮询包装——反复"看一眼"直到条件成立或超时，因此 README 示例中aiAct→aiWaitFor→aiAssert的组合分别对应"执行—等待—终态校验"三种语义。

这类视觉断言的价值在于：它校验的是"用户真正看到的效果"。传统 DOM 断言无法覆盖<canvas>渲染内容、像素级高亮、原生 App 界面，而截图断言天然覆盖这些场景。

Benchmark 表现与运行成本

README 给出三组基准测试成绩（数据来自官方报告，以仓库文档表述为准）：

各报告包含运行配置与任务结果；AndroidWorld 报告还说明了环境与校验器的调整。

运行成本方面，基于截图的 UI 操作无需向模型发送庞大的 DOM 树。在上述 AppControlBench 评测中，Midscene 搭配 Doubao Seed 2.1 Turbo 完成了 60 个任务的评测，模型调用总费用为 0.59 美元，其中 58 个任务通过；官方报告提供逐任务费用与不同模型的对比。

模型选择：Midscene 支持Qwen3.x、Doubao-Seed-2.1、GLM-4.6V、gemini-3.5-flash、UI-TARS等多模态模型，也包括可自托管的开源选项。你可以先使用单模型，再按场景组合规划模型与视觉模型（对应前文resolveModelRuntime('default' | 'planning')的双运行时设计）；在数据提取与页面理解场景中，仍可按需选择携带 DOM。

仓库文档侧也内置了 benchmark 数据的测试用例，例如 app-control-bench-data.test.ts，用于保证站点展示的评测数据与报告一致。

案例速览

README 列出的典型自动化场景（详见官网 showcase 页）：

• Web 自动化：在浏览器中自动注册 GitHub 表单并通过所有字段校验；
• iOS 自动化：美团下单咖啡；自动点赞 @midscene_ai 的第一条推文；
• Android 自动化：懂车帝查看小米 SU7 参数；预订圣诞节酒店；
• 车机测试：机械臂 + 视觉 + 语音方案（社区案例）。

这些案例的测试数据也沉淀在仓库中，例如 test-data 目录包含android-booking.json（预订酒店）、android-dongchedi-su7.json（懂车帝 SU7）、ios-meituan.json（美团）等报告数据，与 showcase 一一对应，可用于查看真实执行报告的结构。

Testing Kit：把 GUI 自动化组织成测试工程

README 的第二大支柱是"开箱即用"的 Testing Kit：测试框架、可观测性和集成 API，帮助将 GUI 自动化组织为可持续维护的 E2E 测试工程。

Midscene Test：声明式意图与可编程工程分离

Midscene Test（npm 包@midscene/test，Beta）将声明式的测试意图与可编程的工程实现分离：用 YAML 编写 UI 流程和预期结果，用可复用的 TypeScript 节点（Node）封装 API 调用、数据准备和清理操作。例如一条退款用例：先通过 API 准备订单，再通过 UI 申请退款并验证结果，在同一个工作流中完成。

从 packages/test 的源码结构看，该框架确实提供了 README 所述的全部能力：

• src/cli/：项目脚手架、节点注册表（registry）、用例收集与运行（collection、case-runner、test-project-runner）；
• src/engine/与src/parser/：YAML 用例的解析与执行引擎；
• src/report/：测试运行报告的生成；
• tests/：覆盖platform-test-entries、project-nodes-cli、test-run-report等能力的测试用例。

框架提供项目脚手架、平台预设（Web / Android / iOS / Harmony 各有 node 封装，见 android-nodes、ios-nodes 等测试文件）、生命周期钩子、重试，以及执行项目之间的隔离与并发。它还根据已注册的节点及其参数定义生成 Markdown 参考文档，让人和 AI Agent 都能了解可用能力，共同编写和维护用例——这是"面向 AI 时代"的 E2E 框架的定位所在：测试用例本身成为 AI 可读、可写、可维护的资产。

内置可观测性

交互式 HTML 报告展示截图、元素定位、AI 决策过程，以及操作和断言结果。Midscene Test 会记录每个 AI 步骤和自定义业务操作的输入、输出、耗时和状态；报告与运行日志为开发者和 AI Agent 提供排查失败所需的上下文。

报告能力在仓库中是一个独立的应用工程 apps/report：src/components/下有 60 余个组件负责详情面板、时间线、主题切换等交互，e2e 目录用 YAML 描述了报告自身的端到端测试（report-single.yaml、theme-toggle.yaml、timeline-interaction.yaml等）；报告数据的抽取与模板工具见 extract-test-data-from-html.ts。packages/core/src/report.ts、report-generator.ts、report-html-template.ts则负责报告内容的生成与内嵌。另外，通过 Playground 还可以直接在界面上试验和调整指令——Playground 的前端在 packages/visualizer 与 packages/playground-app。

丰富的 API，融入现有测试体系

README 总结的四大 Agent API 与源码对应关系：

• aiAct：自主执行多步流程（agent.ts）；
• aiTap/aiInput/aiHover/aiRightClick/aiDoubleClick：单步操作（agent.ts），最终都收敛到callActionInActionSpace；
• aiAssert：视觉断言（agent.ts）；
• aiQuery：结构化数据提取（agent.ts，支持泛型返回类型）。

借助 Playwright、Puppeteer 或 JavaScript SDK，这些 API 可以与已有代码、测试夹具和断言组合，在现有测试框架中引入视觉能力。AI 编程 Agent 也可以通过 Midscene Skills 操作界面——核心包中已包含 skill 目录。

开始使用：四条上手路径

与 README「开始使用」一节对应的仓库落点：

1. 在 Playground 中体验 Midscene：编写脚本前，先交互式试验自然语言操作、数据提取和视觉断言。可以从 Chrome 插件开始（实现见 packages/web-integration/src/chrome-extension），也可以启动移动端或桌面端 Playground（桌面端 Playground 见 apps/studio 这个 Electron 应用，移动端见 packages/android-playground、packages/ios-playground 等包）。
2. 通过 SDK 或 YAML 编写测试：从 Playwright、Puppeteer 或 Midscene Test 开始（本文前面各节均有对应的源码入口）。
3. 让 AI Agent 操作界面：安装 Midscene Skills。
4. 测试其他平台：按 Android / iOS / HarmonyOS / 桌面端指南操作，各平台包位置见前文表格。

仓库结构总览与工程约定

如果你需要在仓库内继续深入，以下结构图与 README 的能力划分一一对应：

packages/ core/ # Agent 基类、任务执行、模型接入、报告生成（@midscene/core） web-integration/ # Web 平台：Playwright/Puppeteer/CDP/Chrome 插件（@midscene/web） android/ # Android 设备控制 + scrcpy 浏览器投屏 ios/ # WebDriverAgent 客户端 harmony/ # hdc 设备通道 computer/ # 桌面端原生键鼠（Windows/macOS/Linux 由 computer-* 薄封装） test/ # Midscene Test：YAML 用例 + TS 节点框架（@midscene/test） visualizer/ # Playground 可视化前端 playground-app/ # 跨平台 Playground 应用组件 recorder/ # 操作录制器（时间线回放、YAML 生成） shared/ # 日志、工具、Agent 工具协议 apps/ report/ # HTML 报告应用（含 e2e 测试） studio/ # 桌面端 Studio（Electron） playground/ # Web Playground site/ # 官方文档站（docs/zh、docs/en 全部文档源文件） chrome-extension/ # Chrome 插件工程

工程侧的约定（来自 package.json 与 AGENTS.md）：monorepo 使用 pnpm workspace（pnpm-workspace.yaml）+ nx 编排构建（nx run-many --target=build）；Node 要求^20.19.0 || ^22.12.0 || >=24.0.0，pnpm>=9.3.0；代码风格由 Biome 管理（biome.json），测试以 rstest/vitest 为主，AI 相关评测通过pnpm test:ai单独执行。文档站 apps/site 基于 rspress，中文文档源文件位于 apps/site/docs/zh，可作为 README 各链接指向的官方文档的本地版本阅读。

资源、社区与许可

• 文档：官方文档站（仓库内源文件在 apps/site/docs/zh 与 apps/site/docs/en）。
• 示例项目：midscene-example（外部仓库）；仓库内另有 packages/test/example/web-midscene 示例工程。
• API 参考：官网 reference 页，对应仓库 apps/site/docs/zh 中的参考文档。
• 社区：Discord、X（@midscene_ai）、飞书交流群（入口见 README.zh.md）。
• 社区生态（Awesome Midscene）：midscene-ios（iOS Mirror 自动化）、midscene-pc（Windows/macOS/Linux 的 PC 操作设备）、midscene-pc-docker（预装 Docker 镜像）、Midscene-Python（Python SDK）、midscene-java（两个 Java SDK 实现）等社区扩展。
• 技术致谢：Rsbuild / Rslib（构建）、UI-TARS 与 Qwen-VL（开源多模态模型）、scrcpy 与 yume-chan（浏览器控制 Android）、appium-adb 与 appium-webdriveragent（ADB / XCTest 桥接）、YADB（文本输入性能）、libnut-core（跨平台原生键鼠）、Puppeteer 与 Playwright（浏览器自动化）。
• 许可：MIT（LICENSE）。

引用

如果你在研究或项目中使用了 Midscene.js，官方建议引用：

@software{Midscene.js, author = {Xiao Zhou, Tao Yu, YiBing Lin}, title = {Midscene.js: GUI Agent for E2E Testing.}, year = {2025}, publisher = {GitHub}, url = {https://github.com/web-infra-dev/midscene} }

小结

Midscene 的技术主张可以压缩为一句话：用视觉替代选择器，用同一套 Agent API 覆盖所有平台，用 Testing Kit 把一次性自动化沉淀为工程。从本文梳理的源码路径可以看到：Agent 基类（packages/core）负责"观察—规划—执行—断言"的核心循环，各平台包（web/android/ios/harmony/computer）只负责截图获取与动作下发，Midscene Test（packages/test）在其上再叠加 YAML 用例、TS 节点、重试与报告等工程能力。若要动手实践，最短路径是：配置一个多模态模型 → 用PlaywrightAgent+aiAct/aiWaitFor/aiAssert跑通第一个视觉测试 → 打开 HTML 报告定位每一步的截图与决策 → 再逐步迁移到 Midscene Test 的 YAML + Node 工程形态。

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