Midscene.js 搭配 Playwright 实操4 步搭出 AI 视觉定位 UI 自动化测试【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene本文基于真实上手经验讲清 Midscene.js 和 Playwright 如何配合做 UI 自动化测试Midscene.js 负责 AI 视觉定位与决策Playwright 负责驱动浏览器执行。4 个最小配置步骤跑通第一个用例并整理定位失败的常见原因与应对办法。视觉定位解决了什么问题先打个比方用 DOM 选择器定位元素有点像凭房间号清单找办公室——只要房间号id、class 这些标记不改你每次都能找到可一旦物业重新编号前端重构、样式改版整份清单就废了你得挨个重查。视觉定位的做法完全不同它相当于人自己走进去看。你只要说点右上角那个红色的结算按钮Midscene.js 就对着页面截图找到它房间号怎么变都无所谓。传统选择器方案还有几个够不着的场景视觉定位正好补上没有语义化标注的元素纯图标按钮、自定义渲染的控件DOM 里往往查不到稳定选择器DOM 工具看不见的区域canvas绘制的内容、跨域 iframe、原生应用界面验证的不是存在而是看起来对颜色、高亮、布局、加载状态这些光靠判断节点是否存在是做不到的。Midscene.js 的思路就是只依赖截图把当前页面交给多模态模型看由模型理解内容、规划动作。你像真人测试一样用自然语言描述目标和验证条件即可。跑通第一个 AI 测试用例最小配置步骤整个过程分 4 步按官方文档走一遍大约半天含等模型配置生效的时间。安装依赖在测试项目中安装midscene/web以及你原本就在用的playwright、playwright/test。这一步没有任何特殊配置。配置 AI 模型Midscene.js 本身不带模型你需要准备一个具备 UI 定位能力的多模态模型如 Qwen-VL、Doubao、Gemini 等文档里有一份支持列表把模型名称、API Key、接口地址写进.env文件。⚠️ 注意这一步是最容易卡住新手的环节模型选得不对后面所有用例都会失败。扩展测试实例Midscene.js 提供PlaywrightAiFixture用它把 Playwright 的test包一层。之后用例里就能直接拿到aiTap、aiInput、aiAssert这些 AI 方法同时在 Playwright 配置文件里加上 Midscene 的 reporter用于生成测试报告。运行并查看报告跑完测试后控制台会输出报告文件路径用浏览器打开。报告里能逐步看到每一步的截图、元素定位框、模型规划的步骤和执行耗时——用例失败时基本靠它排查。用一段话概括操作逻辑你在用例里写一句在搜索框输入 Headphones 并回车Midscene.js 会先截屏让模型规划出找到搜索框 → 输入 → 按回车的动作序列并给出元素坐标然后 Playwright 执行真正的点击和输入。描述用自然语言就行不用写选择器。下图是官方 Playground 里的演示零代码即可先体验一遍这套流程确认指令有效后再搬进代码Midscene.js 与 Playwright 如何分工两者的关系可以一句话概括Midscene.js 是眼睛和大脑Playwright 是手和腿。职责承担方具体做什么感知Midscene.js对当前页面截屏交给多模态模型理解决策Midscene.js把自然语言拆解为动作序列算出目标元素坐标执行Playwright真正执行点击、输入、滚动、页面跳转环境Playwright启动浏览器、管理标签页、并行执行等待与断言双方配合Midscene.js 用视觉判断页面就绪了没aiWaitFor、aiAssertPlaywright 提供底层的加载与网络等待顺带解释一个概念Bridge 模式。上面讲的是脚本启动浏览器的场景如果你想控制的是本机已经登录好的 Chrome比如带着 Cookie 的账户可以让浏览器装 Midscene 扩展开启 Bridge Mode扩展通过 WebSocket 桥接本地的 Midscene SDK。这样脚本和你手动操作的是同一个浏览器登录态不用重新折腾。避坑清单视觉定位失败的常见原因按踩到概率从高到低排元素点错或定位不到原因提示词太笼统页面有两个提交按钮或目标元素太小、和周围元素长得很像。解法在描述里补充相对位置和视觉特征例如右上角红色的购物车图标仍然不准就对该次调用开启deepLocate它会多跑一轮模型调用专门提高定位精度代价是更慢。原生下拉框的选项点不到原因页面用原生select实现下拉框时展开的选项面板是操作系统渲染的不在页面截图里模型自然看不见。解法Midscene 默认开启了forceChromeSelectRendering强制由 Chrome 渲染下拉框使其出现在截图中。排查时先看报告截图如果点击后截图里确实没有选项面板基本就是这个原因。截图超时waiting for fonts to load原因Playwright 截图前默认等字体加载完成在 CI、容器或网络慢的环境里可能一直等不完。解法设置环境变量PW_TEST_SCREENSHOT_NO_FONTS_READY1跳过字体等待。用例时灵时不灵时序问题原因靠固定sleep等页面网络一慢就错过时机。解法用aiWaitFor让 AI 按页面状态判断就绪而不是猜秒数。另外 Midscene 在每个动作后会自动等网络空闲跳转默认 5 秒、点击输入类默认 2 秒超时值可以按环境调。执行时间和模型开销偏高原因每次定位都是一次甚至多次模型调用。解法启用元素缓存element cache——记录已经定位成功的结果页面没变化时直接复用坐标不再重复问模型。下图中启用缓存后同一搜索流程的总耗时是 0.94 秒报告里每个步骤会标注是否命中缓存。用了 Firefox / WebKit 报奇怪的错原因Midscene 的部分 Web 能力依赖 Chrome DevTools ProtocolCDP。解法Web 场景固定用 Chromium这也是文档的默认建议。本地预览窗口持续闪动原因viewport 的deviceScaleFactor和系统像素比不匹配高分屏常见。解法把它设成浏览器实际的window.devicePixelRatio。不影响截图和自动化只影响肉眼看预览的体验。什么时候该用、什么时候不该用✅适合用的场景前端迭代快、选择器维护成本高的页面——重构后选择器失效视觉定位大概率还认得出DOM 工具够不着的地方canvas、跨域 iframe、纯图标按钮、无语义标注的自定义控件需要验证用户看到的效果颜色、高亮、布局、加载动效而不仅仅是节点存在与否新业务的探索性测试和快速原型想先跑起来再谈优化。⚠️谨慎或不建议的场景对执行时间极其敏感的高频回归套件AI 定位比选择器慢一个量级且每次调用都有模型成本。对稳定的核心链路Playwright 原生 API 依然是更优选择要求 100% 复现的判定场景模型输出有不确定性同类页面偶尔会有不同理解关键断言要在报告里抽查确认高风险操作资金、删除AI 误操作后果不可逆的地方建议保留人工确认或改用确定性的原生定位。实际项目里最省心的做法是混合策略稳定步骤走 Playwright 原生 API复杂、易变、DOM 难以触达的步骤交给 AI 视觉定位。这也是官方文档的推荐姿势不必二选一。写在最后选择器回答的是元素在哪AI 视觉定位回答的是这是什么、该怎么操作——把 Midscene.js 的感知决策和 Playwright 的驱动执行拼在一起你的用例就不再随每次前端重构而塌方。资源导航官方文档集成到 Playwright含 fixture 配置与 FAQ官方文档基本概念aiAct/aiTap/aiAssert等 API 的取舍官方文档快速开始零代码 Playground 体验入口【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考