Midscene.js 搭配 Playwright 做视觉 E2E 测试的完整实践指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene假设你的团队维护着一个中等规模的 Playwright微软开源的浏览器自动化库测试工程几百条用例跑在 CI 上页面每做一次组件重构一批选择器selector指用于在 DOM 树中寻址元素的 CSS/类名表达式就会集体失效CI 整片变红修复工作从验证业务退化成追前端实现。更麻烦的一类页面是 canvas 绘制的图表、跨域 iframe、以及移动端原生应用——它们的界面根本没有稳定可寻址的 DOMDocument Object Model浏览器内存中描述页面结构的树形模型选择器路线在这些地方几乎没有发挥空间。Midscene.js 就是为这个困境设计的它是一个面向 E2E 测试end-to-end test模拟用户从界面入口到业务结果的全链路验证的 GUI Agent可以理解为像人一样看着屏幕操作软件的 AI 智能体。它的做法是让多模态大模型能同时理解图像和文本的模型直接分析页面截图判断结账按钮在哪个坐标、筛选结果是否符合预期再把这些判断交给 Playwright 去执行点击和输入。用例本身用自然语言描述不再与某个 class 名耦合。这个仓库GUI Agent for E2E TestingMIT 协议当前版本 1.12.5同时覆盖了 Web、Android、iOS、HarmonyOS 和桌面端且支持接入 Qwen、Doubao、GLM、UI-TARS 等可自托管的开源模型。本文基于仓库内的真实文档和源码讲清楚三件事Midscene.js 与 Playwright 的分工原理、把现有 Playwright 项目迁移到视觉路线的四个落地步骤以及来自官方基准报告和文档的实测数据与适用边界。Midscene.js 与 Playwright 如何分工感知、规划与执行先把职责划分讲清楚。整条链路里Playwright 负责执行启动浏览器、导航、截图、分发鼠标键盘事件Midscene.js 负责感知与决策拿到截图后交给多模态模型得到元素坐标或步骤计划再回传给 Playwright 执行。两边通过一个 page 级对象PlaywrightAgent衔接它对已有的 Playwright page 实例做包装不改变你现有的浏览器生命周期管理。Agent 的核心循环在aiAct上给定一句自然语言目标例如搜索耳机把第一件加入购物车它会执行观察截图 → 规划下一步 → 定位元素 → 执行操作 → 再观察的循环直到目标达成或触发重规划次数上限。与之并列的还有两类 API即时交互类aiTap、aiInput、aiScroll每次只执行一个固定动作不规划多步和界面理解类aiAssert做视觉断言、aiQuery从界面提取结构化数据、aiBoolean回答界面状态问题。断言也走视觉路线——选中的套餐有蓝色边框和勾这种描述可以直接校验颜色、高亮和布局这正是选择器断言很难覆盖的部分。模型侧Midscene 采用纯视觉定位不依赖 DOM 树也不做额外的元素标注。好处是 Token 消耗只与页面分辨率和任务复杂度相关不会随页面 DOM 规模膨胀且同一套 API 可以操作 canvas、跨域 iframe 和移动端界面代价是对模型能力有要求只能选对 GUI 操作稳定的多模态模型而不是任意 LLM。复杂场景下可以在默认模型之上叠加 Planning 模型负责多步规划和 Insight 模型负责数据提取与断言按需分工详见模型策略文档。配套的可观测性是这套架构能落地的关键每次运行都会生成一个交互式 HTML 报告逐步展示截图、元素定位框、AI 的决策过程和断言结果。调试失败用例时开发者或 AI 编码助手都可以基于同一份报告定位问题而不是靠猜。落地四步把现有 Playwright 项目迁移到视觉路线第一步如何把 Midscene.js 集成进现有 Playwright 工程不需要替换框架只需要加装一层 AI 能力。安装midscene/web依赖配置模型服务的环境变量后用PlaywrightAiFixture扩展现有的 test 实例// e2e/fixture.ts import { test as base } from playwright/test; import { PlaywrightAiFixture } from midscene/web/playwright; export const test base.extend(PlaywrightAiFixture({ cache: { id: headphone-search }, // 启用规划与元素定位缓存 }));之后测试用例就能直接使用注入的aiInput、aiTap、aiAssert等 fixturetest(search headphone, async ({ aiInput, aiTap, aiWaitFor, aiQuery, aiAssert }) { await aiInput(搜索框, { value: Headphones }); await aiTap(搜索按钮); await aiWaitFor(搜索结果列表已加载, { timeoutMs: 5000 }); const items await aiQuery{ name: string; price: number }[]( 搜索结果中的商品{name: string, price: number}[], ); await aiAssert(界面左侧有类目筛选功能); });这样做的原因是改造面最小既有的page、goto、断言、报告体系全部保留Midscene 的 AI 能力以 fixture测试框架注入的预置实例形式叠加进来。两点工程注意一是浏览器推荐 Chromium因为部分能力依赖 Chrome DevTools ProtocolCDPChrome 提供的调试与自动化协议Firefox 和 WebKit 上依赖 CDP 的路径可能报错二是在playwright.config.ts的 reporter 中加入midscene/web/playwright-reporter让 AI 步骤并入 Playwright 自己的报告体系merged模式多用例合一separate模式每用例独立。完整步骤见Playwright 集成文档。第二步选择用例编写方式aiAct 与显式编排如何取舍流程不稳定、存在条件分支例如若出现 Cookie 弹窗先关闭的用例交给aiActAgent 基于最新界面状态持续规划天然适配页面变化但每次运行都消耗模型调用。流程明确且长期稳定的用例用 JavaScript 显式编排先用aiQuery取出数据在代码里写循环和分支执行路径完全确定代价是只覆盖代码已经预见的 UI 变化。官方文档给出的取舍原则很直接默认用aiAct编排代码越来越难维护或成功率持续下降时改用aiAct。对于小尺寸或易混淆的元素可以在单次调用上加deepLocate参数换取更高的定位精度代价是多一次模型调用。第三步如何配置视觉定位缓存压低回归运行的模型开销这是回归测试场景最值得做的一步。Midscene 缓存两类内容aiAct类操作的步骤规划以指令文本为键以及 Web 场景下元素定位的 XPath一种在 DOM 树中定位节点的路径表达式命中后无需模型即可复点。缓存文件落在./midscene_run/cache默认关闭通过cache: { id: ... }启用后进入读写模式。三个工程要点。其一CI 上推荐只读模式cache: { strategy: read-only }在afterEach中调用agent.flushCache()落盘保证多 worker 并发时缓存写入的一致性。其二缓存失效时会自动回退到模型重新分析如果缓存的规划在运行时失败Midscene 会回退重新规划且不会把回退结果写回原缓存避免把页面状态已被部分改变后的计划固化。其三查询类 APIaiQuery、aiAssert、aiBoolean永远不走缓存断言每次都重新看屏幕——这保证了缓存只加速操作而不稀释验证。详细策略与flushCache({ cleanUnused: true })的清理机制见缓存文档。第四步用 Bridge 模式复用已登录的 Chrome 浏览器有一类测试环境很难在 headless 容器里复刻需要企业 SSO 登录态、内部浏览器插件、特定设备指纹。Midscene 的 Chrome 桥接模式解决的就是这个场景在桌面 Chrome 安装 Midscene 插件后本地脚本通过AgentOverChromeBridge附着到浏览器新建标签页或当前激活标签页复用 cookies、插件和页面状态自动化脚本与人工环境协同工作社区称之为 man-in-the-loop。脚本侧 API 与普通 Agent 完全一致连接时插件会弹出确认窗口可以按每次确认/始终允许控制授权粒度。默认只监听本机127.0.0.1:3766跨机器访问需要显式开启官方文档对此有明确的安全约束说明。需要注意桥接模式会忽略viewportWidth、userAgent、cookie等由桌面浏览器决定的配置项写用例时要把这个前提考虑进去。效果数据官方基准报告与文档中的实测口径先看视觉定位缓存的官方示例同一条脚本未启用缓存时执行耗时 51 秒启用后降至 28 秒。基准测试方面仓库内附有三份独立的 benchmark 报告每个模型覆盖同一批任务口径为 Pass1单次运行通过率指标数据口径AppControlBench 60 任务 Pass196.7%58/60 通过官方报告实测Midscene 1.12.0 Doubao Seed 2.1 TurboiOS SimulatorAppControlBench 60 任务模型成本合计 $0.59官方报告实测按火山引擎官方单价计AndroidWorld Pass193.1%官方报告实测Gemini-3.5-FlashMobileWorld Pass178.6%官方报告实测Gemini-3.6-Flash缓存命中后的回归执行耗时51s → 28s官方文档示例实测Token 消耗随 DOM 规模膨胀不膨胀仅与分辨率和任务复杂度相关官方文档定性描述两点解读。成本数据说明截图路线的开销结构它把发送整个 DOM 树换成了发送一张截图任务数固定时成本基本可预期这对按回归频率估算月度模型账单的团队是实打实的可规划性。MobileWorld 的 78.6% 则提示移动端跨应用任务仍是有难度的区间选型时应把基准报告里的逐任务结果当作参考而不是只看汇总数字。适用边界哪些场景不适合以及常见坑先说替代选择。如果目标页面 DOM 稳定、元素语义清晰纯 Playwright 选择器方案更便宜也更具确定性Midscene 的价值主要体现在三类场景界面频繁迭代导致选择器维护失控、canvas/iframe/原生应用没有可用 DOM、以及需要校验用户实际看到的效果颜色、高亮、布局的断言。混合使用是合理策略稳定路径走选择器脆弱路径走aiAct。然后是几个高频坑均来自官方 FAQ原生select下拉框展开面板由操作系统渲染截图里看不到选项。Midscene 默认开启forceChromeSelectRendering强制由 Chrome 渲染若你关闭了它且遇到点不到下拉项先查报告截图里选项面板是否真的出现。XPath 定位缓存的盲区canvas 内容、跨域 iframe、closed 模式 Shadow DOM、动态生成的 WebGL/SVG 都没有稳定 DOM定位缓存无法命中这些场景每次都会走模型。缓存不是免模型服务页面结构变化会使命中失效回退时需要 AI 服务在线。缓存的定位是加速不是离线。CI 中缓存不命中缓存文件需要提交进仓库随代码分发且确认指令文本与页面环境在两次运行间保持一致。截图字体超时CI 容器里page.screenshot卡在 waiting for fonts to load 时设置环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1规避这是 Playwright 侧的已知问题不是 Midscene 逻辑。本地预览闪动viewport 的deviceScaleFactor与系统像素比不一致会导致窗口闪烁不影响自动化结果但影响调试体验把两者对齐即可。最后一条成本提醒aiAct在每次规划循环都会调用模型天然比即时交互 API 更耗时也更贵复杂任务加deepThink会进一步放大调用次数。规模化使用时优先把流程稳定的部分拆成即时 API 缓存把aiAct留给真正不确定的分支这是控制单用例模型开销最直接的手段。结语Midscene.js 与 Playwright 的组合本质上是把执行与感知解耦Playwright 继续做它最擅长的浏览器驱动多模态模型负责过去必须由人脑完成的那部分——看懂界面、找到元素、判断结果是否成立。它没有让选择器消失而是让没有选择器可用的场景canvas、iframe、原生应用、高频迭代第一次有了可维护的自动化方案。迁移成本集中在模型服务配置与用例改写两步回归收益则体现在选择器维护消失、缓存命中后的执行提速、以及可逐截图审查的失败诊断上。延伸入口官方中文文档docs/重点是Playwright 集成与缓存两篇基准报告AppControlBench、AndroidWorld、MobileWorld源码模块Playwright 集成层 packages/web-integration/src/playwright/Agent 规划与定位核心 packages/core/src/agent/桥接模式实现 packages/web-integration/src/bridge-mode/【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene.js 搭配 Playwright 做视觉 E2E 测试的完整实践指南
Midscene.js 搭配 Playwright 做视觉 E2E 测试的完整实践指南【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene假设你的团队维护着一个中等规模的 Playwright微软开源的浏览器自动化库测试工程几百条用例跑在 CI 上页面每做一次组件重构一批选择器selector指用于在 DOM 树中寻址元素的 CSS/类名表达式就会集体失效CI 整片变红修复工作从验证业务退化成追前端实现。更麻烦的一类页面是 canvas 绘制的图表、跨域 iframe、以及移动端原生应用——它们的界面根本没有稳定可寻址的 DOMDocument Object Model浏览器内存中描述页面结构的树形模型选择器路线在这些地方几乎没有发挥空间。Midscene.js 就是为这个困境设计的它是一个面向 E2E 测试end-to-end test模拟用户从界面入口到业务结果的全链路验证的 GUI Agent可以理解为像人一样看着屏幕操作软件的 AI 智能体。它的做法是让多模态大模型能同时理解图像和文本的模型直接分析页面截图判断结账按钮在哪个坐标、筛选结果是否符合预期再把这些判断交给 Playwright 去执行点击和输入。用例本身用自然语言描述不再与某个 class 名耦合。这个仓库GUI Agent for E2E TestingMIT 协议当前版本 1.12.5同时覆盖了 Web、Android、iOS、HarmonyOS 和桌面端且支持接入 Qwen、Doubao、GLM、UI-TARS 等可自托管的开源模型。本文基于仓库内的真实文档和源码讲清楚三件事Midscene.js 与 Playwright 的分工原理、把现有 Playwright 项目迁移到视觉路线的四个落地步骤以及来自官方基准报告和文档的实测数据与适用边界。Midscene.js 与 Playwright 如何分工感知、规划与执行先把职责划分讲清楚。整条链路里Playwright 负责执行启动浏览器、导航、截图、分发鼠标键盘事件Midscene.js 负责感知与决策拿到截图后交给多模态模型得到元素坐标或步骤计划再回传给 Playwright 执行。两边通过一个 page 级对象PlaywrightAgent衔接它对已有的 Playwright page 实例做包装不改变你现有的浏览器生命周期管理。Agent 的核心循环在aiAct上给定一句自然语言目标例如搜索耳机把第一件加入购物车它会执行观察截图 → 规划下一步 → 定位元素 → 执行操作 → 再观察的循环直到目标达成或触发重规划次数上限。与之并列的还有两类 API即时交互类aiTap、aiInput、aiScroll每次只执行一个固定动作不规划多步和界面理解类aiAssert做视觉断言、aiQuery从界面提取结构化数据、aiBoolean回答界面状态问题。断言也走视觉路线——选中的套餐有蓝色边框和勾这种描述可以直接校验颜色、高亮和布局这正是选择器断言很难覆盖的部分。模型侧Midscene 采用纯视觉定位不依赖 DOM 树也不做额外的元素标注。好处是 Token 消耗只与页面分辨率和任务复杂度相关不会随页面 DOM 规模膨胀且同一套 API 可以操作 canvas、跨域 iframe 和移动端界面代价是对模型能力有要求只能选对 GUI 操作稳定的多模态模型而不是任意 LLM。复杂场景下可以在默认模型之上叠加 Planning 模型负责多步规划和 Insight 模型负责数据提取与断言按需分工详见模型策略文档。配套的可观测性是这套架构能落地的关键每次运行都会生成一个交互式 HTML 报告逐步展示截图、元素定位框、AI 的决策过程和断言结果。调试失败用例时开发者或 AI 编码助手都可以基于同一份报告定位问题而不是靠猜。落地四步把现有 Playwright 项目迁移到视觉路线第一步如何把 Midscene.js 集成进现有 Playwright 工程不需要替换框架只需要加装一层 AI 能力。安装midscene/web依赖配置模型服务的环境变量后用PlaywrightAiFixture扩展现有的 test 实例// e2e/fixture.ts import { test as base } from playwright/test; import { PlaywrightAiFixture } from midscene/web/playwright; export const test base.extend(PlaywrightAiFixture({ cache: { id: headphone-search }, // 启用规划与元素定位缓存 }));之后测试用例就能直接使用注入的aiInput、aiTap、aiAssert等 fixturetest(search headphone, async ({ aiInput, aiTap, aiWaitFor, aiQuery, aiAssert }) { await aiInput(搜索框, { value: Headphones }); await aiTap(搜索按钮); await aiWaitFor(搜索结果列表已加载, { timeoutMs: 5000 }); const items await aiQuery{ name: string; price: number }[]( 搜索结果中的商品{name: string, price: number}[], ); await aiAssert(界面左侧有类目筛选功能); });这样做的原因是改造面最小既有的page、goto、断言、报告体系全部保留Midscene 的 AI 能力以 fixture测试框架注入的预置实例形式叠加进来。两点工程注意一是浏览器推荐 Chromium因为部分能力依赖 Chrome DevTools ProtocolCDPChrome 提供的调试与自动化协议Firefox 和 WebKit 上依赖 CDP 的路径可能报错二是在playwright.config.ts的 reporter 中加入midscene/web/playwright-reporter让 AI 步骤并入 Playwright 自己的报告体系merged模式多用例合一separate模式每用例独立。完整步骤见Playwright 集成文档。第二步选择用例编写方式aiAct 与显式编排如何取舍流程不稳定、存在条件分支例如若出现 Cookie 弹窗先关闭的用例交给aiActAgent 基于最新界面状态持续规划天然适配页面变化但每次运行都消耗模型调用。流程明确且长期稳定的用例用 JavaScript 显式编排先用aiQuery取出数据在代码里写循环和分支执行路径完全确定代价是只覆盖代码已经预见的 UI 变化。官方文档给出的取舍原则很直接默认用aiAct编排代码越来越难维护或成功率持续下降时改用aiAct。对于小尺寸或易混淆的元素可以在单次调用上加deepLocate参数换取更高的定位精度代价是多一次模型调用。第三步如何配置视觉定位缓存压低回归运行的模型开销这是回归测试场景最值得做的一步。Midscene 缓存两类内容aiAct类操作的步骤规划以指令文本为键以及 Web 场景下元素定位的 XPath一种在 DOM 树中定位节点的路径表达式命中后无需模型即可复点。缓存文件落在./midscene_run/cache默认关闭通过cache: { id: ... }启用后进入读写模式。三个工程要点。其一CI 上推荐只读模式cache: { strategy: read-only }在afterEach中调用agent.flushCache()落盘保证多 worker 并发时缓存写入的一致性。其二缓存失效时会自动回退到模型重新分析如果缓存的规划在运行时失败Midscene 会回退重新规划且不会把回退结果写回原缓存避免把页面状态已被部分改变后的计划固化。其三查询类 APIaiQuery、aiAssert、aiBoolean永远不走缓存断言每次都重新看屏幕——这保证了缓存只加速操作而不稀释验证。详细策略与flushCache({ cleanUnused: true })的清理机制见缓存文档。第四步用 Bridge 模式复用已登录的 Chrome 浏览器有一类测试环境很难在 headless 容器里复刻需要企业 SSO 登录态、内部浏览器插件、特定设备指纹。Midscene 的 Chrome 桥接模式解决的就是这个场景在桌面 Chrome 安装 Midscene 插件后本地脚本通过AgentOverChromeBridge附着到浏览器新建标签页或当前激活标签页复用 cookies、插件和页面状态自动化脚本与人工环境协同工作社区称之为 man-in-the-loop。脚本侧 API 与普通 Agent 完全一致连接时插件会弹出确认窗口可以按每次确认/始终允许控制授权粒度。默认只监听本机127.0.0.1:3766跨机器访问需要显式开启官方文档对此有明确的安全约束说明。需要注意桥接模式会忽略viewportWidth、userAgent、cookie等由桌面浏览器决定的配置项写用例时要把这个前提考虑进去。效果数据官方基准报告与文档中的实测口径先看视觉定位缓存的官方示例同一条脚本未启用缓存时执行耗时 51 秒启用后降至 28 秒。基准测试方面仓库内附有三份独立的 benchmark 报告每个模型覆盖同一批任务口径为 Pass1单次运行通过率指标数据口径AppControlBench 60 任务 Pass196.7%58/60 通过官方报告实测Midscene 1.12.0 Doubao Seed 2.1 TurboiOS SimulatorAppControlBench 60 任务模型成本合计 $0.59官方报告实测按火山引擎官方单价计AndroidWorld Pass193.1%官方报告实测Gemini-3.5-FlashMobileWorld Pass178.6%官方报告实测Gemini-3.6-Flash缓存命中后的回归执行耗时51s → 28s官方文档示例实测Token 消耗随 DOM 规模膨胀不膨胀仅与分辨率和任务复杂度相关官方文档定性描述两点解读。成本数据说明截图路线的开销结构它把发送整个 DOM 树换成了发送一张截图任务数固定时成本基本可预期这对按回归频率估算月度模型账单的团队是实打实的可规划性。MobileWorld 的 78.6% 则提示移动端跨应用任务仍是有难度的区间选型时应把基准报告里的逐任务结果当作参考而不是只看汇总数字。适用边界哪些场景不适合以及常见坑先说替代选择。如果目标页面 DOM 稳定、元素语义清晰纯 Playwright 选择器方案更便宜也更具确定性Midscene 的价值主要体现在三类场景界面频繁迭代导致选择器维护失控、canvas/iframe/原生应用没有可用 DOM、以及需要校验用户实际看到的效果颜色、高亮、布局的断言。混合使用是合理策略稳定路径走选择器脆弱路径走aiAct。然后是几个高频坑均来自官方 FAQ原生select下拉框展开面板由操作系统渲染截图里看不到选项。Midscene 默认开启forceChromeSelectRendering强制由 Chrome 渲染若你关闭了它且遇到点不到下拉项先查报告截图里选项面板是否真的出现。XPath 定位缓存的盲区canvas 内容、跨域 iframe、closed 模式 Shadow DOM、动态生成的 WebGL/SVG 都没有稳定 DOM定位缓存无法命中这些场景每次都会走模型。缓存不是免模型服务页面结构变化会使命中失效回退时需要 AI 服务在线。缓存的定位是加速不是离线。CI 中缓存不命中缓存文件需要提交进仓库随代码分发且确认指令文本与页面环境在两次运行间保持一致。截图字体超时CI 容器里page.screenshot卡在 waiting for fonts to load 时设置环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1规避这是 Playwright 侧的已知问题不是 Midscene 逻辑。本地预览闪动viewport 的deviceScaleFactor与系统像素比不一致会导致窗口闪烁不影响自动化结果但影响调试体验把两者对齐即可。最后一条成本提醒aiAct在每次规划循环都会调用模型天然比即时交互 API 更耗时也更贵复杂任务加deepThink会进一步放大调用次数。规模化使用时优先把流程稳定的部分拆成即时 API 缓存把aiAct留给真正不确定的分支这是控制单用例模型开销最直接的手段。结语Midscene.js 与 Playwright 的组合本质上是把执行与感知解耦Playwright 继续做它最擅长的浏览器驱动多模态模型负责过去必须由人脑完成的那部分——看懂界面、找到元素、判断结果是否成立。它没有让选择器消失而是让没有选择器可用的场景canvas、iframe、原生应用、高频迭代第一次有了可维护的自动化方案。迁移成本集中在模型服务配置与用例改写两步回归收益则体现在选择器维护消失、缓存命中后的执行提速、以及可逐截图审查的失败诊断上。延伸入口官方中文文档docs/重点是Playwright 集成与缓存两篇基准报告AppControlBench、AndroidWorld、MobileWorld源码模块Playwright 集成层 packages/web-integration/src/playwright/Agent 规划与定位核心 packages/core/src/agent/桥接模式实现 packages/web-integration/src/bridge-mode/【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考