视觉驱动Web UI自动化：Midscene与Playwright实战解析

1. 从“选择器地狱”到“视觉驱动”为什么我们需要另一种 Web UI 自动化思路做过 Web UI 自动化的朋友大概率都经历过这样的场景凌晨两点CI 流水线又红了打开报告一看某个按钮的id从submit-btn变成了submitBtn或者某个元素被包进了一个新的div里XPath 直接失效。你改完选择器第二天前端同学重构了一下组件库一切又回到原点。这种“选择器地狱”是传统 Web UI 自动化最让人头疼的问题也是我这些年一直在寻找更稳定方案的根本原因。Midscene 这个工具第一次看到它的时候我其实是带着怀疑态度的。它的核心卖点是“视觉驱动”——用自然语言描述你要操作什么它通过视觉识别和 LLM 的理解能力去定位元素并执行操作。听起来很美好但做自动化测试的人都知道“听起来美好”和“实际能用”之间往往隔着一条鸿沟。不过在深入使用了一段时间之后我发现它在特定场景下确实能解决一些传统方案很难处理的问题尤其是在页面结构频繁变动、元素定位不稳定、或者需要快速验证业务流程的场景里。这篇文章不是一篇“官方文档翻译”也不是“Hello World 级别的入门教程”。我想从一个实际使用者的角度把 Midscene 在 Web UI 自动化中的定位、核心原理、与 Playwright 的配合方式、脚本化的具体实现、以及我在实际项目中踩过的坑完整地梳理一遍。如果你正在做 Web UI 自动化或者对“视觉驱动 LLM”这个方向感兴趣这篇文章应该能给你一些直接的参考。需要提前说明的是Midscene 并不是要替代 Playwright 或 Selenium 这类传统框架它更像是在这些框架之上加了一层“智能定位层”。你可以把它理解成一个“翻译官”你用自然语言告诉它要做什么它负责把这句话翻译成具体的页面操作。这个翻译过程依赖两个核心能力——视觉识别和 LLM 推理。视觉识别负责“看”页面LLM 负责“理解”你的意图并决定怎么操作。2. Midscene 的核心机制拆解它到底是怎么“看懂”页面的2.1 视觉驱动与 DOM 驱动的本质区别传统 Web UI 自动化的定位逻辑是“DOM 驱动”的。你写一个选择器框架去 DOM 树里找匹配的节点找到就操作找不到就报错。这个过程的本质是“字符串匹配”——你的选择器和 DOM 节点的属性之间做匹配。问题在于DOM 结构是前端实现细节而前端实现细节是会变的。今天用classbtn-primary明天可能就变成classbutton primary你的选择器就废了。Midscene 的“视觉驱动”走的是另一条路。它不依赖 DOM 结构来定位元素而是通过截图 视觉识别模型来“看”页面。你告诉它“点击登录按钮”它会先截取当前页面然后通过视觉模型识别出页面上哪些区域可能是按钮再结合 LLM 的语义理解判断哪个按钮最可能是“登录按钮”。这个过程更接近人类使用浏览器的方式——我们不会去检查 DOM 结构我们就是“看”页面然后“点”我们看到的按钮。这两种方式的差异在页面结构稳定的时候不明显但在页面频繁变动的时候差异巨大。DOM 驱动的方式页面结构一变选择器就可能失效视觉驱动的方式只要按钮还在页面上、文字没变、位置没有大到离谱它大概率还能找到。这就是 Midscene 的核心价值所在。2.2 Midscene 与 Playwright 的协作关系很多人第一次接触 Midscene 的时候会有一个疑问它和 Playwright 是什么关系是替代还是补充答案是补充而且是深度补充。Midscene 本身并不直接操作浏览器它依赖 Playwright 来完成实际的浏览器控制。你可以这样理解Playwright 负责“动手”Midscene 负责“动脑”。当你调用 Midscene 的ai方法时它内部会通过 Playwright 截取当前页面截图然后把截图和你的自然语言指令一起发给视觉模型和 LLM模型返回操作指令比如“点击坐标 (x, y)”或“在某个输入框输入文本”Midscene 再通过 Playwright 执行这些操作。这个协作模式的好处是你不需要放弃已有的 Playwright 生态。你可以在一个 Playwright 测试用例里混合使用传统的选择器定位和 Midscene 的视觉定位。比如对于稳定的登录表单你可以用传统选择器对于频繁变动的业务页面你可以用 Midscene。这种灵活性在实际项目中非常实用。2.3 视觉模型与 LLM 的分工Midscene 内部其实用了两种模型能力视觉模型和语言模型。视觉模型负责“看”页面识别出页面上的元素、文字、布局语言模型负责“理解”你的指令并决定怎么操作。举个例子你输入指令“在搜索框里输入‘自动化测试’并点击搜索按钮”。视觉模型会先识别出页面上的搜索框和搜索按钮的位置语言模型则会理解你的意图是“先找到搜索框输入文本再找到搜索按钮点击”。然后 Midscene 会把这两个结果结合起来生成具体的操作序列。这个分工很重要因为它决定了 Midscene 的能力边界。如果页面上的元素视觉上不明显比如两个按钮长得一模一样视觉模型可能分不清如果你的指令语义模糊比如“点击那个按钮”但页面上有多个按钮语言模型也可能判断错误。理解这个分工有助于你在实际使用中写出更准确的指令。3. 环境搭建与基础配置从零开始跑通第一个 Midscene 脚本3.1 环境准备与依赖安装在开始之前你需要确保本地环境满足以下条件Node.js 18 或以上版本一个可用的 Playwright 环境Midscene 的 npm 包安装步骤并不复杂但有几个细节需要注意。首先Playwright 的安装建议用官方推荐的方式npm init playwrightlatest这个命令会帮你初始化一个 Playwright 项目包括配置文件、示例测试等。如果你已经有 Playwright 项目可以跳过这一步。接下来安装 Midscenenpm install midscene/web --save-dev这里有一个坑需要注意Midscene 的版本和 Playwright 的版本之间存在兼容性关系。我在早期使用的时候因为 Playwright 版本太新导致 Midscene 的截图功能异常。后来降级到 Playwright 1.40.x 才恢复正常。所以建议你在安装之前先查一下 Midscene 官方文档里推荐的 Playwright 版本范围。另外Midscene 需要调用视觉模型和 LLM所以你需要配置相应的 API Key。目前它支持多种模型提供商具体配置方式会在下一节详细说明。3.2 模型配置与 API Key 管理Midscene 的模型配置是通过环境变量或配置文件来完成的。我推荐用.env文件来管理 API Key这样可以避免把密钥硬编码在代码里。一个典型的.env文件长这样MIDSCENE_OPENAI_API_KEYyour_api_key_here MIDSCENE_OPENAI_BASE_URLhttps://api.openai.com/v1 MIDSCENE_MODEL_NAMEgpt-4o这里有几个实操心得第一模型选择很关键。我试过用gpt-4o和gpt-4-turbo前者在视觉识别和指令理解上明显更准但成本也更高。如果你的测试用例不多建议直接用gpt-4o如果用例量大可以考虑用gpt-4-turbo做日常回归关键用例用gpt-4o。第二API Key 的额度要留足。视觉模型的调用成本比纯文本模型高不少因为每次调用都要传截图。一个中等复杂度的页面一次操作可能消耗几千个 token。如果你的测试套件有上百个用例费用会比较可观。第三建议配置一个代理地址如果你在国内的话否则 API 调用可能会超时。具体配置方式取决于你使用的模型提供商这里不展开。3.3 第一个 Midscene 脚本从打开页面到点击按钮环境配好之后我们来写第一个脚本。这个脚本的目标很简单打开一个页面找到搜索框输入关键词点击搜索按钮。const { chromium } require(playwright); const { Midscene } require(midscene/web); (async () { const browser await chromium.launch({ headless: false }); const page await browser.newPage(); const midscene new Midscene(page); await page.goto(https://example.com); await midscene.ai(在搜索框里输入“自动化测试”); await midscene.ai(点击搜索按钮); await page.waitForTimeout(3000); await browser.close(); })();这段代码的核心是midscene.ai()方法。你传入一个自然语言指令Midscene 会负责把它翻译成具体的页面操作。这里有几个细节值得注意第一headless: false是我建议在调试阶段使用的配置。因为 Midscene 的视觉识别依赖于截图如果你用 headless 模式截图可能和实际显示有差异导致识别不准。调试阶段用有头模式确认没问题后再切换到 headless。第二waitForTimeout是一个“笨办法”但在 Midscene 里有时候是必要的。因为视觉识别和 LLM 推理都需要时间如果你紧接着执行下一个操作可能会因为页面还没更新而失败。更好的做法是用waitForLoadState或waitForSelector但在视觉驱动的场景下这些传统方法不一定适用。第三指令的写法很重要。“在搜索框里输入‘自动化测试’”比“输入自动化测试”更准确因为它明确了操作目标。Midscene 的指令越具体识别准确率越高。4. 脚本化实战用 Midscene 处理复杂业务场景4.1 表单填写与多步骤流程表单填写是 Web UI 自动化里最常见的场景也是最容易出问题的场景。传统的做法是给每个输入框写选择器但一旦表单结构变化所有选择器都要改。用 Midscene 的话你可以用自然语言描述整个填写过程。比如一个注册表单有用户名、邮箱、密码、确认密码四个字段传统写法可能是await page.fill(#username, testuser); await page.fill(#email, testexample.com); await page.fill(#password, password123); await page.fill(#confirm-password, password123); await page.click(#submit-btn);用 Midscene 的话可以写成await midscene.ai(在用户名输入框里填写“testuser”); await midscene.ai(在邮箱输入框里填写“testexample.com”); await midscene.ai(在密码输入框里填写“password123”); await midscene.ai(在确认密码输入框里填写“password123”); await midscene.ai(点击提交按钮);看起来代码变长了但稳定性提升了。因为 Midscene 不依赖id或class它依赖的是“用户名输入框”这个语义。只要页面上还有一个地方写着“用户名”它就能找到。不过这里有一个坑如果页面上有多个“密码”相关的输入框比如“密码”和“确认密码”Midscene 可能会混淆。我的做法是在指令里加上更明确的描述比如“在标有‘确认密码’的输入框里填写”这样识别准确率会高很多。4.2 动态内容与异步加载的处理现代 Web 应用大量使用异步加载页面上的内容不是一次性渲染出来的。传统的做法是用waitForSelector等待某个元素出现但如果你不知道具体的选择器这个方法就用不了。Midscene 在处理异步加载时有一个天然优势它是“看”页面的。如果页面还在加载截图里可能没有目标元素Midscene 会识别失败。但你可以通过重试机制来解决这个问题。我的做法是封装一个retryAi函数async function retryAi(midscene, instruction, maxRetries 3) { for (let i 0; i maxRetries; i) { try { await midscene.ai(instruction); return; } catch (error) { if (i maxRetries - 1) throw error; await new Promise(resolve setTimeout(resolve, 2000)); } } }这个函数会在指令执行失败时等待 2 秒后重试最多重试 3 次。实测下来对于大多数异步加载场景这个重试机制已经够用了。另外Midscene 本身也提供了一些等待相关的配置比如设置超时时间、设置重试次数等。具体参数可以在初始化 Midscene 时传入。4.3 断言与结果验证自动化测试的核心不只是“操作”还有“验证”。Midscene 提供了一些断言相关的能力但和传统的断言方式不太一样。传统的断言是“检查某个元素是否存在”或“检查某个元素的文本是否等于预期值”。Midscene 的断言更偏向于“视觉验证”——你可以让它检查页面上是否出现了某个内容或者某个区域的状态是否符合预期。比如你可以这样写const result await midscene.ai(检查页面上是否显示“注册成功”); console.log(result);Midscene 会返回一个结果告诉你它“看到”了什么。这个结果可能是一个布尔值也可能是一段描述性的文本具体取决于你的配置。这里有一个实操心得Midscene 的断言结果不如传统断言那么精确。传统断言是“是/否”的二元结果Midscene 的断言可能会返回“我看到了‘注册成功’这几个字但不确定是不是你要找的”。所以如果你的测试需要严格的断言建议还是用传统方式如果只是做“大致验证”Midscene 的断言够用了。5. 常见问题与排查技巧实录5.1 识别失败为什么它找不到我要的元素识别失败是使用 Midscene 时最常见的问题。原因通常有以下几种第一页面截图不完整。如果页面有滚动条截图可能只截到了可视区域目标元素在可视区域之外。解决办法是在截图前先滚动到目标位置或者配置 Midscene 截取整个页面。第二元素视觉特征不明显。如果两个按钮长得一模一样视觉模型可能分不清。解决办法是在指令里加上更多上下文比如“点击页面底部的提交按钮”而不是“点击提交按钮”。第三指令语义模糊。如果你说“点击那个按钮”但页面上有多个按钮LLM 也不知道你指的是哪个。解决办法是把指令写具体比如“点击标有‘登录’的按钮”。第四模型能力不足。如果你用的是比较弱的视觉模型识别准确率会下降。解决办法是换用更强的模型比如gpt-4o。5.2 性能与成本优化Midscene 的每次操作都需要调用视觉模型和 LLM这会带来两个问题速度慢、成本高。速度方面一次操作可能需要 2-5 秒比传统选择器定位慢很多。如果你的测试套件有几百个用例整体执行时间会很长。我的优化建议是对于稳定的页面和元素用传统选择器对于频繁变动的页面用 Midscene。混合使用可以在稳定性和速度之间取得平衡。成本方面视觉模型的调用成本比纯文本模型高不少。我的优化建议是第一尽量合并指令比如把“在用户名输入框输入 testuser”和“在密码输入框输入 password123”合并成一条指令“在用户名输入框输入 testuser在密码输入框输入 password123”第二对于不需要视觉识别的操作比如导航到某个 URL直接用 Playwright 的 API第三设置合理的重试次数避免因为一次失败就反复调用模型。5.3 与传统测试框架的集成Midscene 可以和 pytest、Jest、Mocha 等测试框架集成。集成的关键在于把 Midscene 的操作封装成测试步骤然后用测试框架来组织这些步骤。以 Jest 为例你可以这样写const { chromium } require(playwright); const { Midscene } require(midscene/web); describe(登录流程, () { let browser; let page; let midscene; beforeAll(async () { browser await chromium.launch(); page await browser.newPage(); midscene new Midscene(page); }); afterAll(async () { await browser.close(); }); test(用户可以用正确的凭据登录, async () { await page.goto(https://example.com/login); await midscene.ai(在用户名输入框里填写“testuser”); await midscene.ai(在密码输入框里填写“password123”); await midscene.ai(点击登录按钮); const result await midscene.ai(检查页面上是否显示“欢迎回来”); expect(result).toBeTruthy(); }); });这个集成方式的好处是你可以用 Jest 的断言和报告功能同时享受 Midscene 的视觉驱动能力。5.4 常见问题速查表问题现象可能原因解决办法识别不到元素截图不完整滚动到目标位置后再截图识别到错误元素指令语义模糊在指令里加上更多上下文操作超时模型响应慢增加超时时间或换用更快的模型成本过高调用次数太多合并指令混合使用传统选择器断言不准确视觉验证的局限性关键断言用传统方式辅助断言用 Midscene页面加载慢导致失败异步加载封装重试机制等待页面稳定后再操作6. 视觉驱动自动化的边界与适用场景6.1 什么场景适合用 Midscene根据我的实际使用经验Midscene 在以下几类场景里表现最好第一页面结构频繁变动的项目。如果你的前端团队经常重构组件、改类名、调布局传统选择器会频繁失效Midscene 的视觉驱动方式能大幅降低维护成本。第二需要快速验证业务流程的场景。比如产品经理说“帮我验证一下从注册到下单的完整流程”你用 Midscene 可以快速写一个脚本跑通不需要花时间研究每个元素的选择器。第三元素定位困难的场景。有些元素没有稳定的id或class或者被动态生成传统方式很难定位Midscene 可以通过视觉特征来识别。第四跨平台或跨设备的测试。Midscene 的视觉驱动方式不依赖具体的 DOM 结构理论上可以在不同平台之间复用同一套指令。6.2 什么场景不适合用 MidsceneMidscene 也不是万能的以下场景建议谨慎使用第一对执行速度要求极高的场景。Midscene 的每次操作都需要调用模型速度比传统选择器慢很多。如果你的测试套件需要在几分钟内跑完Midscene 可能不适合。第二对断言精度要求极高的场景。Midscene 的断言是“视觉验证”不如传统断言精确。如果测试结果需要严格的是/否判断建议用传统方式。第三预算有限的场景。视觉模型的调用成本不低如果测试量大费用会比较可观。第四页面元素视觉特征不明显的场景。如果页面上有大量长得一样的元素视觉模型很难区分这时候传统选择器反而更可靠。6.3 混合策略传统选择器 视觉驱动在实际项目中我通常采用混合策略对于稳定的、不常变动的页面比如登录页、导航栏用传统选择器对于频繁变动的、结构复杂的页面比如业务表单、动态列表用 Midscene。这样既能保证稳定性又能控制成本和速度。具体来说我会在 Playwright 的测试用例里根据页面模块的稳定性来决定用哪种方式。比如// 稳定的登录页用传统选择器 await page.fill(#username, testuser); await page.fill(#password, password123); await page.click(#login-btn); // 频繁变动的业务页面用 Midscene await midscene.ai(在搜索框里输入“订单编号”); await midscene.ai(点击搜索按钮); await midscene.ai(在结果列表里找到第一条记录并点击查看详情);这种混合方式在实际项目中非常实用既能享受传统选择器的速度和精度又能享受 Midscene 的灵活性和稳定性。7. 我踩过的坑与实操心得7.1 截图质量对识别率的影响Midscene 的识别准确率高度依赖截图质量。我遇到过几次因为截图分辨率太低导致识别失败的情况。后来发现Playwright 默认的视口大小是 1280x720这个分辨率下有些小字体的按钮识别起来比较吃力。把视口调大到 1920x1080 之后识别率明显提升。另外如果你的页面有动画效果截图可能会截到动画中间状态导致识别失败。我的做法是在截图前先等待动画结束或者禁用页面上的动画效果。7.2 指令写法的经验总结写 Midscene 指令是一门“手艺”。我总结了几条经验第一指令要具体。“点击按钮”不如“点击标有‘提交’的按钮”。第二指令要唯一。“在输入框里输入”不如“在用户名输入框里输入”。第三指令要分步。复杂的操作拆成多条指令比一条长指令更可靠。第四指令要符合页面上的实际文字。如果页面上写的是“登 录”中间有空格你写“登录”可能识别不到。7.3 模型选择的权衡我试过多种模型组合最终发现gpt-4o在视觉识别和指令理解上表现最好但成本也最高。对于日常回归测试我会用gpt-4-turbo对于关键业务流程的验证我会用gpt-4o。这个组合在成本和准确性之间取得了不错的平衡。另外模型的选择也会影响执行速度。gpt-4o的响应速度比gpt-4-turbo快一些但差距不大。如果你对速度有要求可以考虑用更小的模型但识别准确率会下降。7.4 调试技巧如何快速定位问题当 Midscene 操作失败时快速定位问题很重要。我的调试流程是这样的第一步检查截图。Midscene 在每次操作时都会截图你可以把截图保存下来看看页面上到底显示了什么。第二步检查指令。看看你的指令是否足够具体、是否和页面上的文字一致。第三步检查模型返回。Midscene 会返回模型的推理结果你可以看看模型“理解”了什么是不是和你的意图一致。第四步简化场景。如果复杂指令失败试着拆成简单指令看看是哪一步出了问题。这套流程帮我解决了很多问题也让我对 Midscene 的能力边界有了更清晰的认识。8. 从脚本化到工程化Midscene 在团队协作中的落地建议8.1 脚本组织与复用在团队协作中Midscene 脚本的组织方式很重要。我的建议是把常用的操作封装成函数比如“登录”、“搜索”、“填写表单”等然后在不同的测试用例里复用。async function login(midscene, username, password) { await midscene.ai(在用户名输入框里填写“${username}”); await midscene.ai(在密码输入框里填写“${password}”); await midscene.ai(点击登录按钮); } async function search(midscene, keyword) { await midscene.ai(在搜索框里输入“${keyword}”); await midscene.ai(点击搜索按钮); }这样组织的好处是当页面变化时你只需要修改封装函数不需要修改每个测试用例。8.2 与 CI/CD 的集成Midscene 可以集成到 CI/CD 流水线中但需要注意几点第一API Key 的管理。不要把 API Key 硬编码在代码里用环境变量或密钥管理服务。第二超时设置。Midscene 的操作比传统方式慢CI 的超时时间要相应调大。第三失败重试。网络波动或模型响应慢可能导致偶发失败建议配置重试机制。第四报告生成。Midscene 的操作日志和截图可以集成到测试报告里方便排查问题。8.3 团队协作中的注意事项在团队中使用 Midscene有几个问题需要提前考虑第一成本分摊。视觉模型的调用成本不低需要明确谁来承担这笔费用。第二指令规范。团队需要统一指令的写法避免因为个人风格不同导致识别率波动。第三模型版本管理。不同版本的模型识别效果可能不同需要锁定版本或定期评估。第四与传统自动化的分工。明确哪些场景用 Midscene哪些场景用传统方式避免混用导致维护混乱。9. 视觉驱动自动化的未来可能性Midscene 目前还处于比较早期的阶段但它的方向很有意思。随着视觉模型和 LLM 能力的提升视觉驱动自动化的准确率和速度都会改善。我比较期待的几个方向是第一更精准的元素定位减少对指令具体性的依赖第二更快的响应速度让视觉驱动接近传统选择器的效率第三更好的断言能力让视觉验证也能做到精确判断。从工程实践的角度来看Midscene 目前最适合的场景是“辅助”而不是“替代”。它可以帮你处理那些传统方式很难搞定的场景但不需要完全替代现有的自动化体系。混合使用、各取所长是我目前认为最务实的做法。如果你正在做 Web UI 自动化并且被选择器维护问题困扰我建议你花半天时间试试 Midscene。它可能不会解决你所有的问题但它提供了一种新的思路而这种思路在某些场景下确实能带来实实在在的效率提升。