Midscene + Playwright：视觉驱动 Web UI 自动化实战指南

1. 为什么视觉驱动是 Web UI 自动化的一条新路子做过 Web UI 自动化的人大概都有过这种体验页面改了一个 class 名或者前端把按钮从button换成了div rolebutton你辛辛苦苦维护的几百行选择器脚本一夜之间全红。传统的 Playwright、Selenium 方案本质上是结构化定位——靠 DOM 树里的 id、class、XPath、CSS Selector 去锚定元素。这套逻辑在页面稳定时非常可靠但一旦前端迭代频繁维护成本就会指数级上升。Midscene 这个工具切入的角度不太一样。它把视觉作为定位的第一入口你告诉它点击登录按钮它通过截图 多模态大模型理解页面找到那个按钮的坐标然后驱动 Playwright 去执行真实的鼠标点击。换句话说选择器不再由你手写而是由模型在运行时看出来。这就把传统脚本里最脆弱的一环——硬编码定位——给绕开了。这套思路特别适合几类场景一是前端迭代快、class 名天天变的中后台系统二是元素定位极其复杂、嵌套 iframe 或者动态渲染的页面三是你想快速写一批冒烟级的端到端验证不想在定位上花太多时间。当然它也不是银弹后面我会详细讲它在哪些地方会翻车。这篇文章我会从 Midscene 和 Playwright 的协作原理讲起然后给出完整的环境搭建、脚本编写、断言设计、调试排错的实操链路最后聊聊我在实际项目里踩过的坑和总结出来的经验。如果你正在用 Playwright 或者 pytest 做自动化想给现有体系加一层视觉能力这篇应该能帮你少走不少弯路。2. Midscene 与 Playwright 的协作原理拆解2.1 它不是替代 Playwright而是寄生在 Playwright 之上很多人第一次听到 Midscene会误以为它是一个全新的浏览器自动化框架跟 Playwright 是竞争关系。实际不是。Midscene 的定位更像是一个智能代理层它本身不实现浏览器驱动而是复用 Playwright或 Puppeteer已经建立好的页面会话。具体流程是这样的你用 Playwright 正常启动一个 browser context 和 page然后把 page 交给 Midscene 的 Agent。Agent 在需要执行动作时会先调用 Playwright 的截图接口拿到当前视口的图像把图像连同你的自然语言指令一起发给多模态模型模型返回一个结构化的动作描述——比如点击坐标 (x, y)或者在某个输入框输入文本。Agent 再把这个动作翻译成 Playwright 的page.mouse.click(x, y)或page.keyboard.type()之类的底层调用。这个链路里Playwright 负责手和眼真实的浏览器操作和截图模型负责大脑理解页面、决定点哪里。两者职责清晰所以你可以继续用 Playwright 的所有能力——等待、网络拦截、多标签页、cookie 管理——只是把找元素这一步外包给了模型。2.2 视觉定位和 DOM 定位的本质差异理解这个差异才能理解 Midscene 的边界在哪里。DOM 定位是符号匹配你写.login-btn浏览器在 DOM 树里精确查找 class 为 login-btn 的节点。它是确定性的、毫秒级的、零成本的。缺点是符号一旦变了就失效。视觉定位是语义匹配模型看到一张截图理解这是一个登录页面右上角有个蓝色按钮写着登录然后给出坐标。它是概率性的、需要网络往返的、有 token 成本的。优点是它对 DOM 结构不敏感——只要人眼还能认出那个按钮模型大概率也能认出来。这里有个关键点视觉定位的稳定性取决于视觉特征的稳定性而不是代码结构的稳定性。如果设计师把按钮从蓝色改成绿色、从右上角挪到中间模型一样会懵。所以它解决的是代码变了但界面没变的问题不是界面彻底改版的问题。这一点想清楚了你就不会对它抱有不切实际的期待。2.3 一次完整动作的生命周期我把一次agent.aiClick(登录按钮)的内部过程拆成几个阶段方便你后面调试时定位问题截图阶段Playwright 截取当前页面可能是全页也可能是视口取决于配置。预处理阶段图像可能被缩放、压缩以适配模型的输入限制。推理阶段图像 指令发给多模态模型模型输出动作意图和坐标。坐标映射阶段模型返回的坐标是基于它看到的图像尺寸需要按比例映射回真实页面坐标。执行阶段Playwright 在映射后的坐标上执行真实鼠标/键盘事件。验证阶段可选再次截图确认动作是否生效。任何一步出问题最终表现都是点了没反应或者点错地方。后面排错章节我会针对每一步给出排查方法。3. 环境搭建从零到跑通第一个视觉脚本3.1 依赖安装与版本选择Midscene 目前主要以 npm 包形式提供配合 Node.js 环境使用。如果你团队是 Python 技术栈也可以用它提供的 HTTP 服务模式但原生体验还是 TypeScript/JavaScript 更顺。基础依赖大致是这几块# 初始化项目 npm init -y # 安装 Playwright 和 Midscene npm install playwright midscene/web # 安装 Playwright 的浏览器内核 npx playwright install chromium这里有个坑我踩过npx playwright install在国内网络环境下经常卡住或者失败因为浏览器内核是从境外 CDN 下载的。解决办法是设置镜像环境变量或者提前把内核包放到缓存目录。如果你在公司内网最好让运维把内核包同步到内部源。版本选择上Playwright 建议用较新的稳定版1.40 以上因为 Midscene 依赖了一些较新的截图和 CDP 接口。Node.js 建议 18 LTS 以上低版本可能在 ESM 模块加载上出问题。3.2 模型接入的配置方式Midscene 需要一个大模型来提供视觉理解能力。配置通常通过环境变量注入大致长这样# 模型服务配置示例 export MIDSCENE_MODEL_API_KEYyour-api-key export MIDSCENE_MODEL_BASE_URLhttps://your-model-endpoint export MIDSCENE_MODEL_NAMEyour-vision-model注意模型必须支持图像输入多模态纯文本模型无法工作。选型时优先考虑对中文界面识别准确、响应延迟低的模型因为每次动作都要走一次推理延迟会直接叠加到测试总时长上。我实测下来单次视觉动作的端到端延迟在 2 到 6 秒之间取决于模型响应速度和页面复杂度。这意味着一个包含 20 个步骤的用例光模型推理就要花一两分钟。所以视觉驱动不适合做高频回归更适合做关键路径的冒烟验证或者作为传统脚本的补充。3.3 第一个可运行的最小示例先跑通一个最简单的场景打开一个页面用自然语言点击一个元素。import { chromium } from playwright; import { Agent } from midscene/web; async function main() { const browser await chromium.launch({ headless: false }); const page await browser.newPage(); await page.goto(https://example.com/login); const agent new Agent(page); // 用自然语言描述动作 await agent.aiAction(在用户名输入框中输入 testuser); await agent.aiAction(在密码输入框中输入 password123); await agent.aiAction(点击登录按钮); // 等待页面跳转后做断言 await page.waitForTimeout(2000); const result await agent.aiQuery(当前页面是否显示了欢迎信息返回 true 或 false); console.log(登录结果:, result); await browser.close(); } main();跑通这个示例你就理解了 Midscene 的基本用法aiAction负责执行动作aiQuery负责从页面提取信息。两者都是自然语言驱动不需要写选择器。3.4 目录结构建议项目稍微大一点就要考虑组织方式。我一般这样分project/ ├── agents/ # 封装好的页面 Agent ├── cases/ # 测试用例 ├── fixtures/ # 测试数据 ├── utils/ # 工具函数 └── reports/ # 输出报告把每个页面的常用操作封装成 Agent 方法用例层只调用语义化方法这样即使底层从视觉定位换成 DOM 定位用例层也不用改。这个抽象层是长期维护的关键。4. 脚本编写把自然语言指令写稳4.1 指令描述的颗粒度控制自然语言指令最大的陷阱是太模糊或太啰嗦。我总结了一个原则描述要包含动作 目标 必要的区分特征。反面例子点击按钮 —— 页面上有五个按钮模型不知道点哪个。点击那个在页面右上角、蓝色的、写着登录的按钮它旁边有个头像图标 —— 信息过载模型反而容易抓错重点。正面例子点击页面顶部的登录按钮在标有手机号的输入框中输入 13800138000点击列表第一行的编辑链接关键是把唯一区分特征给出来。如果页面上有多个相似元素用位置顶部、左侧、第一行或上下文在某个标题下方来限定。4.2 输入类操作的注意事项输入操作比点击更容易出问题因为涉及焦点、清空、输入法等因素。几个实操要点先确保输入框获得焦点有些页面需要先点击输入框才能输入直接 type 可能无效。稳妥做法是先aiAction(点击XX输入框)再aiAction(输入XXX)。处理已有内容如果输入框里已有默认值直接输入会追加而不是替换。可以先aiAction(清空XX输入框)。避免特殊字符某些特殊字符在自然语言指令里可能被模型误解尽量用引号包裹要输入的内容。// 稳妥的输入流程 await agent.aiAction(点击用户名输入框); await agent.aiAction(清空用户名输入框); await agent.aiAction(在用户名输入框中输入 testuser001);4.3 断言设计aiQuery 的用法与陷阱断言是自动化测试的灵魂。Midscene 提供了aiQuery让你用自然语言从页面提取信息然后自己写断言逻辑。const loginStatus await agent.aiQuery( 页面顶部是否显示了用户名如果显示返回用户名文本否则返回 null ); if (loginStatus null) { throw new Error(登录失败未检测到用户名); }这里有个重要陷阱aiQuery 返回的是模型的理解结果不是确定性的 DOM 查询。模型可能因为截图模糊、字体太小、颜色对比度低而误判。所以关键断言不要只依赖视觉最好和 DOM 断言结合。我的做法是视觉断言用于快速冒烟确认页面大致状态关键业务断言仍然用 Playwright 的expect(page.locator(...))来做保证确定性。两者互补而不是互相替代。4.4 等待与同步策略视觉驱动的等待逻辑和传统脚本不同。传统脚本可以waitForSelector视觉脚本没有选择器可等。常见做法有几种固定等待waitForTimeout简单粗暴但不可靠页面快了浪费时间慢了还是失败。轮询式 aiQuery循环调用 aiQuery 检查某个条件是否满足满足则继续。混合等待先用 Playwright 等待网络空闲或某个 DOM 标志再用视觉确认。// 轮询等待示例 async function waitForText(agent, text, timeout 15000) { const start Date.now(); while (Date.now() - start timeout) { const found await agent.aiQuery(页面上是否出现了${text}返回 true 或 false); if (found true) return true; await new Promise(r setTimeout(r, 1000)); } throw new Error(等待文本${text}超时); }这个轮询函数我在多个项目里复用比固定等待稳得多。注意轮询间隔不要太短否则会疯狂消耗模型调用次数。5. 调试与排错视觉脚本翻车了怎么查5.1 点了没反应的完整排查链路这是最常见的问题。我的排查顺序是这样的第一步确认截图内容。让 Agent 把每次动作前的截图保存下来看看模型到底看到了什么。如果截图是白屏、加载中、或者被弹窗遮挡那问题不在模型而在页面状态。第二步确认坐标映射。如果截图正常但点击位置偏了可能是图像缩放比例和真实视口不一致。检查 Playwright 的 viewport 设置和截图尺寸是否匹配。第三步确认元素可交互。有些元素视觉上存在但被透明遮罩层挡住或者 z-index 有问题。模型看到的是视觉层但真实点击会被遮罩拦截。这种情况需要先关闭遮罩。第四步确认动作时序。页面可能有动画模型截图时元素还在移动等点击时位置已经变了。加一个短暂的稳定等待通常能解决。5.2 模型看错的典型场景有些页面元素对模型特别不友好我列几个高频翻车场景场景表现应对小字体密集文本模型识别错行放大页面缩放比例低对比度按钮模型找不到临时高亮或改用 DOM 定位图标无文字模型猜错含义指令里描述图标形状或位置动态加载列表模型看到旧内容等待加载完成再截图多语言混排模型理解偏差指令用页面主语言描述这些场景不是 Midscene 独有的问题任何视觉方案都会遇到。关键是提前识别在脚本里做针对性处理。5.3 成本与性能的平衡每次视觉动作都是一次模型调用有 token 成本和延迟。一个用例跑下来如果动作太多成本会很难看。几个优化思路合并动作能一步完成的不要拆成三步。比如在用户名输入框输入 testuser 并在密码框输入 pass123可以合并成一条指令。减少不必要的截图只在关键节点做视觉确认中间过程用 Playwright 原生操作。缓存页面状态同一页面连续多个动作如果页面没变可以考虑复用上一次的截图理解结果需要自己实现缓存层。分级策略核心路径用视觉边缘路径用 DOM。我一般会把视觉动作控制在单个用例 10 次以内超过就说明这个用例可能不适合纯视觉方案。5.4 日志与可观测性视觉脚本的调试比传统脚本难因为为什么模型这么判断是个黑盒。所以日志要尽可能详细const agent new Agent(page, { generateReport: true, // 生成可视化报告 autoPrintReportMsg: true, // 控制台打印进度 reportPath: ./reports // 报告输出目录 });Midscene 自带报告功能会把每一步的截图、指令、模型返回都记录下来。这个报告在排查问题时非常有用建议默认开启。另外我还会在关键节点手动console.log当前页面 URL 和标题方便定位是哪一步出的问题。6. 与现有测试体系的融合实践6.1 和 pytest 的配合方式如果团队主力是 Python pytestMidscene 的 Node 生态会有点割裂。两种融合思路一是通过子进程调用pytest 用例里用subprocess调用 Node 脚本把结果通过 stdout 或 JSON 文件回传。这种方式隔离性好但进程启动有开销。二是通过 HTTP 服务把 Midscene 封装成一个常驻的 Node 服务暴露 REST 接口pytest 通过 HTTP 调用。这种方式适合用例量大、需要复用的场景但要多维护一个服务。我倾向第二种因为视觉模型的初始化成本高常驻服务能摊薄这部分开销。6.2 和传统 Playwright 脚本的混合编排最实用的模式是混合编排一个用例里稳定的、结构化的操作用原生 Playwright易变的、视觉特征明显的操作用 Midscene。// 混合编排示例 await page.goto(/dashboard); // 原生导航 await page.waitForLoadState(networkidle); // 原生等待 await agent.aiAction(点击左侧菜单的订单管理); // 视觉操作 await page.waitForURL(**/orders); // 原生等待跳转 const rowCount await page.locator(table tr).count(); // 原生断言这样既享受了视觉定位对结构变化的鲁棒性又保留了原生操作的确定性和速度。关键是划清边界导航、等待、数据断言用原生语义化点击和复杂定位用视觉。6.3 在 CI 中的落地要点视觉脚本进 CI 有几个额外注意点模型服务要稳定CI 环境访问模型服务如果超时整个用例就挂了。建议加超时重试和降级策略。截图要留存CI 失败时报告里的截图是唯一能复现问题的线索务必归档。并发要控制多个用例同时调模型可能触发限流。建议串行或小并发。成本要监控把每次运行的模型调用次数和 token 消耗记录下来避免成本失控。我在 CI 里给视觉用例单独设了一个 job和传统用例分开跑这样即使视觉部分不稳定也不会阻塞主流程的回归。7. 我踩过的坑和几条实在的经验先说一个最典型的坑。有次我写了个用例指令是点击提交按钮本地跑得好好的CI 上十次有三次失败。排查了半天发现是 CI 的视口尺寸和本地不一样页面布局变了提交按钮从可见区域被挤到了折叠线以下模型截图时根本没看到它。解决办法是在启动 browser 时显式固定 viewport 尺寸保证本地和 CI 一致。第二个坑是关于中文指令的。模型对中文的理解整体不错但遇到专业术语或者页面上的英文混排时偶尔会理解偏差。我的经验是指令语言尽量和页面主语言一致。页面是中文的就用中文描述页面是英文的就用英文描述。混着来容易出问题。第三个坑是等待策略。一开始我图省事到处用waitForTimeout(3000)结果用例总时长爆炸而且该失败的地方还是失败。后来改成轮询式等待总时长降了一半稳定性还提升了。这个改动看起来小但对整个测试套件的体验影响很大。最后分享一个我觉得最有价值的经验不要试图用视觉驱动覆盖所有场景。它的价值在于处理那些结构定位搞不定的硬骨头而不是取代所有传统脚本。把它当成工具箱里的一把特殊螺丝刀而不是万能扳手。想清楚这一点你在项目里引入它的时候就不会走偏也不会因为期待过高而失望。真正稳定的自动化体系永远是多种定位策略的组合而不是单一方案的独舞。