Midscene.js 技术解析面向 E2E 测试的视觉驱动 GUI Agent 与 Testing Kit【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidsceneGUI 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 基类及其全部 APIinsight.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_TIMEOUTcache任务缓存策略取值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[] }, ): Promisevoid { 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 结构可以逐一印证各平台包的位置平台仓库包说明Webpackages/web-integrationPlaywright / Puppeteer / 浏览器桥接含 Chrome 插件相关代码Androidpackages/androidADB scrcpy 浏览器预览scrcpy-manager.ts 管理投屏进程iOSpackages/ios基于 WebDriverAgent 的 ios-webdriver-client.tsHarmonyOSpackages/harmony基于 hdc 的 hdc.ts 设备通道桌面packages/computer原生键鼠windows-pointer.ts、windows-dpi.ts 各平台薄封装包 computer-mac / computer-win / computer-linux此外 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为输入让多模态模型判断自然语言描述的界面状态是否成立。aiWaitForagent.ts则是对断言的轮询包装——反复看一眼直到条件成立或超时因此 README 示例中aiAct→aiWaitFor→aiAssert的组合分别对应执行—等待—终态校验三种语义。这类视觉断言的价值在于它校验的是用户真正看到的效果。传统 DOM 断言无法覆盖canvas渲染内容、像素级高亮、原生 App 界面而截图断言天然覆盖这些场景。Benchmark 表现与运行成本README 给出三组基准测试成绩数据来自官方报告以仓库文档表述为准BenchmarkPass1对应评测使用的模型AndroidWorld93.1%Gemini-3.5-FlashMobileWorld78.6%Gemini-3.6-FlashAppControlBench96.7%Doubao Seed 2.1 Turbo各报告包含运行配置与任务结果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 Testnpm 包midscene/testBeta将声明式的测试意图与可编程的工程实现分离用 YAML 编写 UI 流程和预期结果用可复用的 TypeScript 节点Node封装 API 调用、数据准备和清理操作。例如一条退款用例先通过 API 准备订单再通过 UI 申请退款并验证结果在同一个工作流中完成。从 packages/test 的源码结构看该框架确实提供了 README 所述的全部能力src/cli/项目脚手架、节点注册表registry、用例收集与运行collection、case-runner、test-project-runnersrc/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/reportsrc/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.tsaiTap/aiInput/aiHover/aiRightClick/aiDoubleClick单步操作agent.ts最终都收敛到callActionInActionSpaceaiAssert视觉断言agent.tsaiQuery结构化数据提取agent.ts支持泛型返回类型。借助 Playwright、Puppeteer 或 JavaScript SDK这些 API 可以与已有代码、测试夹具和断言组合在现有测试框架中引入视觉能力。AI 编程 Agent 也可以通过 Midscene Skills 操作界面——核心包中已包含 skill 目录。开始使用四条上手路径与 README「开始使用」一节对应的仓库落点在 Playground 中体验 Midscene编写脚本前先交互式试验自然语言操作、数据提取和视觉断言。可以从 Chrome 插件开始实现见 packages/web-integration/src/chrome-extension也可以启动移动端或桌面端 Playground桌面端 Playground 见 apps/studio 这个 Electron 应用移动端见 packages/android-playground、packages/ios-playground 等包。通过 SDK 或 YAML 编写测试从 Playwright、Puppeteer 或 Midscene Test 开始本文前面各节均有对应的源码入口。让 AI Agent 操作界面安装 Midscene Skills。测试其他平台按 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 TestYAML 用例 TS 节点框架midscene/test visualizer/ # Playground 可视化前端 playground-app/ # 跨平台 Playground 应用组件 recorder/ # 操作录制器时间线回放、YAML 生成 shared/ # 日志、工具、Agent 工具协议 apps/ report/ # HTML 报告应用含 e2e 测试 studio/ # 桌面端 StudioElectron playground/ # Web Playground site/ # 官方文档站docs/zh、docs/en 全部文档源文件 chrome-extension/ # Chrome 插件工程工程侧的约定来自 package.json 与 AGENTS.mdmonorepo 使用 pnpm workspacepnpm-workspace.yaml nx 编排构建nx run-many --targetbuildNode 要求^20.19.0 || ^22.12.0 || 24.0.0pnpm9.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、Xmidscene_ai、飞书交流群入口见 README.zh.md。社区生态Awesome Midscenemidscene-iosiOS Mirror 自动化、midscene-pcWindows/macOS/Linux 的 PC 操作设备、midscene-pc-docker预装 Docker 镜像、Midscene-PythonPython SDK、midscene-java两个 Java SDK 实现等社区扩展。技术致谢Rsbuild / Rslib构建、UI-TARS 与 Qwen-VL开源多模态模型、scrcpy 与 yume-chan浏览器控制 Android、appium-adb 与 appium-webdriveragentADB / XCTest 桥接、YADB文本输入性能、libnut-core跨平台原生键鼠、Puppeteer 与 Playwright浏览器自动化。许可MITLICENSE。引用如果你在研究或项目中使用了 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 Testpackages/test在其上再叠加 YAML 用例、TS 节点、重试与报告等工程能力。若要动手实践最短路径是配置一个多模态模型 → 用PlaywrightAgentaiAct/aiWaitFor/aiAssert跑通第一个视觉测试 → 打开 HTML 报告定位每一步的截图与决策 → 再逐步迁移到 Midscene Test 的 YAML Node 工程形态。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考