Midscene.js：基于AI视觉的跨平台UI自动化测试框架实战指南

1. 项目概述当UI测试不再需要“选择器”如果你做过UI自动化测试一定对“选择器”又爱又恨。爱的是它给了我们一个精准定位页面元素的锚点恨的是它太脆弱了。一个看似无关的CSS类名修改、一个DOM结构的微调甚至只是开发同学重构了组件库都可能让你精心编写的测试用例瞬间“失明”报出一堆“Element not found”的错误。维护这些选择器成了自动化测试中最耗时、最令人沮丧的“屎山”搬运工作。Midscene.js的出现正是要彻底解决这个问题。它不是一个在Selenium或Playwright之上修修补补的插件而是一个从底层理念上就截然不同的视觉驱动Vision-Driven的跨平台自动化测试框架。它的核心思想非常直观像人一样去看然后像人一样去操作。它通过AI视觉模型“看”屏幕截图理解界面上的元素按钮、输入框、图标然后驱动鼠标和键盘去执行点击、输入、断言等操作。这意味着你不再需要为每个按钮编写#submit-btn或.ant-btn-primary这样的选择器你只需要告诉AI“点击那个蓝色的‘提交’按钮”。这个项目由字节跳动开源目前在GitHub上已经获得了超过13k的Star并曾登上趋势榜第二其背后是火山引擎、抖音、飞书等大规模产品的真实应用验证。它支持Web、PCmacOS/Windows/Linux、MobileAndroid/iOS/HarmonyOS三大平台真正实现了一套API、一套用例跑遍所有终端。对于那些传统选择器无法触及的领域——比如Canvas绘制的游戏界面、无语义信息的原生应用窗口、跨域的iframe甚至是基于图像渲染的客户端——Midscene提供了一种全新的可能性凡可截图皆可自动化。2. 核心架构与设计哲学拆解2.1 视觉驱动 vs. 传统DOM驱动范式转移要理解Midscene的价值必须从底层对比它与传统框架的差异。传统DOM/无障碍树驱动如Selenium, Playwright, Appium工作原理通过浏览器开发者工具协议CDP或移动设备调试协议获取应用的结构化描述DOM树或无障碍树。测试脚本通过CSS选择器、XPath或资源ID来定位元素。优势执行速度极快定位精准可以获取元素的内部属性如文本内容、样式。致命弱点强耦合测试脚本与应用的实现细节HTML结构、组件ID深度绑定。前端微小的改动就可能导致测试失败。覆盖局限无法操作Canvas、视频、Flash、系统原生对话框等非DOM元素。对于跨域iframe内容访问受限。平台碎片化Web、桌面端、移动端需要不同的驱动和APIPlaywright, WinAppDriver, Appium学习成本和维护成本高。Midscene的视觉驱动范式工作原理截图对目标应用界面进行截图。视觉理解将截图和自然语言指令如“登录按钮”送入多模态大模型如豆包Seed、Qwen-VL。元素定位模型分析图片理解指令语义并返回目标元素在屏幕上的坐标边界框Bounding Box。动作执行框架将坐标转换为对应平台的原生输入事件鼠标点击、键盘输入执行操作。优势实现无关测试关注的是“用户看到什么和做什么”而非“代码怎么写”。UI外观不变测试就不变极大提升了健壮性。突破壁垒只要能截图就能自动化。完美覆盖Canvas、游戏、桌面应用、终端命令行等场景。统一体验用同一套基于自然语言的API描述测试逻辑跨平台执行。挑战与折衷执行速度需要截图、调用模型API、计算坐标比直接DOM操作慢。定位精度依赖于模型对图像的识别能力在元素极其相似或界面动态变化剧烈时可能出错。成本调用商业大模型API会产生费用虽然Midscene也支持开源模型自托管。注意Midscene并非要完全取代Playwright等传统工具。它的定位是互补。对于稳定、核心且选择器易于维护的流程用传统方法保证速度对于易变、跨平台或选择器无法工作的场景用Midscene实现覆盖。两者可以通过桥接模式协同工作。2.2 多模型协同策略精度与成本的平衡术Midscene没有把宝押在一个模型上而是设计了一套灵活的多模型组合策略这是其工业级可用性的关键。视觉定位模型Vision-Language Model负责核心的“看图说话”任务即根据指令在截图中框出元素。Midscene内置并推荐了几款经过大量测试验证的模型豆包Seed官方推荐的默认模型由字节内部优化在元素定位的准确性和稳定性上表现突出是“稳妥之选”。Qwen3.7-Plus通义千问的多模态版本定位质量高且提供了可本地部署的开源版本对于注重数据隐私或希望控制成本的企业是绝佳选择。Gemini-3.5-Flash谷歌的模型在多模态理解上能力强大定位表现也很出色作为备选。规划模型Planning Model对于复杂的多步任务如“将商品A加入购物车并结算”单纯定位单个按钮可能不够。规划模型通常是更强的文本大模型会先将自然语言指令分解成一系列原子操作步骤“定位搜索框 - 输入关键词 - 定位搜索按钮 - 点击 - 定位商品A - 点击加入购物车 - ...再交给视觉模型逐步执行。这种“规划执行”的协同大大提升了复杂任务的完成率。这种设计给了开发者极大的灵活性。你可以根据测试场景的复杂度、对精度的要求以及预算来配置模型的使用策略。例如对精度要求极高的支付流程使用豆包Seed对简单的页面跳转断言可以使用更经济的开源模型。3. 核心API与实战入门理论说得再多不如上手一试。我们从一个最简单的Web测试开始感受一下用自然语言写测试是什么体验。3.1 环境搭建与初始化首先确保你的系统已安装Node.js (18)。然后创建一个新项目并安装Midscenemkdir my-midscene-test cd my-midscene-test npm init -y npm install midscene/sdk playwright这里同时安装了Playwright因为Midscene可以桥接到Playwright的浏览器实例进行驱动这是一种常见的混合模式。接下来你需要一个多模态大模型的API Key。以使用豆包Seed为例你需要前往 火山引擎控制台 申请。获得API Key后将其设置为环境变量export MIDSCENE_API_KEYyour-doubao-seed-api-key-here # Windows (PowerShell): $env:MIDSCENE_API_KEYyour-key3.2 第一个视觉驱动测试用例假设我们要测试一个简单的登录页面。传统方式需要写选择器找用户名输入框、密码输入框和登录按钮。用Midscene我们可以这样写test/login.spec.jsconst { chromium } require(playwright); const { Midscene } require(midscene/sdk); (async () { // 1. 用Playwright启动浏览器Midscene负责“看”和“指挥”Playwright负责“开车” const browser await chromium.launch({ headless: false }); // 非无头模式方便观察 const context await browser.newContext(); const page await context.newPage(); await page.goto(https://your-test-app.com/login); // 2. 创建Midscene实例并连接到当前页面 const midscene new Midscene(); await midscene.connect(page); // 桥接模式Midscene控制Playwright的page // 3. 使用自然语言进行自动化操作 try { // 在用户名输入框中输入“testuser” await midscene.aiAct(在用户名输入框中输入 testuser); // 在密码输入框中输入“password123” await midscene.aiAct(在密码输入框中输入 password123); // 点击登录按钮 await midscene.aiAct(点击登录按钮); // 4. 使用视觉断言验证登录后是否跳转到首页并看到了“欢迎”字样 await midscene.aiAssert(当前页面是首页并且包含“欢迎回来”的文本); console.log(✅ 登录测试通过); } catch (error) { console.error(❌ 测试失败, error.message); // Midscene会生成可视化的测试报告包含每一步的截图和模型决策过程 } finally { await browser.close(); } })();运行这个脚本node test/login.spec.js。你会看到浏览器自动打开页面上的元素被自动定位、输入和点击。整个过程你没有写任何一个选择器。3.3 核心API详解Midscene提供了一系列原子API让你能进行更精细的控制aiAct(instruction: string)全能选手。接收一个自然语言指令让模型规划并执行一系列操作来完成它。例如aiAct(搜索苹果手机并加入购物车)。aiTap(instruction: string)精确定位并点击。当你明确只需要点击操作时使用比aiAct意图更清晰。aiFill(instruction: string, text: string)精确定位并输入文本。例如aiFill(找到收货地址输入框, 北京市海淀区)。aiAssert(instruction: string)视觉断言。验证当前界面是否与描述一致。这是UI测试的核心例如aiAssert(弹窗显示“保存成功”)、aiAssert(进度条完成度达到100%)。aiLocate(instruction: string)仅定位不操作。返回元素的位置信息用于自定义后续逻辑。aiScreenshot()获取当前页面的截图可用于自定义的图像比对或存档。实操心得对于简单的原子操作点、输优先使用aiTap和aiFill指令更明确模型理解更准成功率更高。对于复杂的多步流程使用aiAct。断言一定要用aiAssert它是测试逻辑的基石。4. 跨平台自动化实战解析Midscene的“一套API多端运行”并非虚言。我们来看在不同平台上的应用。4.1 Web端与Playwright/Puppeteer深度集成如上例所示Midscene通过connect方法与Playwright或Puppeteer的Page对象连接。这意味着你可以利用Playwright强大的浏览器上下文管理、网络拦截、设备模拟等功能同时享受Midscene视觉驱动的便利。你甚至可以在同一个测试套件中混用两种定位方式稳定的核心导航用Playwright选择器易变的UI交互用Midscene。4.2 移动端Android/iOS真机与模拟器测试移动端测试的痛点在于设备碎片化和原生控件识别。Appium依赖于UIAutomator2/XCUITest同样面临控件ID变化的问题。Midscene的方案是直接使用设备投屏或模拟器截图。const { Midscene, AndroidDevice } require(midscene/sdk); const { exec } require(child_process); (async () { // 1. 连接Android设备需提前开启USB调试 // 这里Midscene可能通过ADB获取屏幕流或要求你提供屏幕截图服务地址 const device await AndroidDevice.connect(emulator-5554); // 设备ID const midscene new Midscene(); await midscene.connect(device); // 连接到设备屏幕 // 2. 像操作Web一样使用自然语言 await midscene.aiAct(在手机主屏幕向上滑动); await midscene.aiAct(点击设置应用图标); await midscene.aiAct(在设置列表中找到并点击“关于手机”); await midscene.aiAssert(页面中显示了设备型号信息); })();对于iOS原理类似需要通过tidevice等工具获取屏幕。Midscene抽象了设备连接层让测试脚本无需关心底层是ADB还是WDA。4.3 桌面端Windows/macOS/Linux自动化原生应用这是传统UI自动化最难啃的骨头。Midscene通过操作系统提供的截图API如macOS的screencaptureWindows的Graphics.Capture获取整个屏幕或指定窗口的图像然后进行操作。# Midscene也支持用YAML定义工作流非常适合与CI/CD集成 name: 自动化文档保存流程 platform: desktop steps: - act: 打开Finder应用程序 - act: 在搜索栏中输入“季度报告.docx” - act: 双击找到的文档文件 - wait: 2s # 等待Word启动 - act: 在Word应用程序中点击顶部菜单栏的“文件” - act: 在下拉菜单中点击“另存为” - fill: instruction: 在文件名输入框中 text: 季度报告_最终版 - act: 点击保存按钮 - assert: 屏幕下方出现“保存成功”的提示横幅你可以通过CLI运行这个YAML文件midscene run workflow.yaml。这对于自动化软件安装、系统配置等重复性桌面任务极具价值。注意事项桌面自动化涉及系统级权限。在macOS上你需要为终端或脚本赋予“屏幕录制”和“辅助功能”权限否则无法截图和模拟输入。这是操作系统安全机制的要求并非框架限制。5. 高级特性与集成方案5.1 Skills让AI Agent替你写测试这是Midscene一个前瞻性的特性。Skills是一组开箱即用的工具允许像GitHub Copilot、Cursor AI或DevIN这样的AI编程Agent通过Midscene CLI来理解和测试你的UI。想象一下这个场景你对着AI说“为这个新提交的登录页写一个测试覆盖成功登录和失败情况”。AI Agent可以启动Midscene CLI。导航到你的登录页。利用explore技能探索页面识别出所有可交互元素。利用generate-test技能生成一套包含多个aiAct和aiAssert的Midscene测试脚本。甚至能自动运行一遍验证脚本是否有效。这直接将UI自动化测试的创作门槛降到了零从“编写测试”进入了“描述测试”的时代。5.2 可视化报告与Playground调试视觉测试是个挑战因为你需要知道模型“看”到了什么、“想”了什么。Midscene内置了强大的报告功能。每一步都有截图测试报告会记录每个aiAct、aiAssert步骤前后的屏幕截图。可视化决策过程报告会高亮显示模型定位到的元素边界框并附上模型对该步骤的理解文本。时间线回放像播放视频一样回放整个测试过程直观定位失败步骤。此外Midscene提供了一个PlaygroundWeb界面。你可以在那里上传截图实时输入指令让模型定位元素快速试验不同的指令表述找到最稳定可靠的描述方式然后再将指令写入正式测试脚本。这是优化测试稳定性的必备工具。5.3 与现有测试生态集成你不需要完全重写现有的测试套件。Midscene可以轻松集成到Jest、Mocha、Vitest、Playwright Test等主流测试运行器中。// 在Playwright Test中使用Midscene import { test, expect } from playwright/test; import { Midscene } from midscene/sdk; test.describe(视觉登录测试, () { let midscene; test.beforeEach(async ({ page }) { await page.goto(/login); midscene new Midscene(); await midscene.connect(page); }); test(成功登录, async () { await midscene.aiFill(用户名输入框, userexample.com); await midscene.aiFill(密码输入框, securepass); await midscene.aiTap(登录按钮); // 混合断言既用视觉断言也用Playwright的原生断言 await midscene.aiAssert(页面跳转到仪表盘); await expect(page).toHaveURL(/dashboard); // 传统URL断言作为双重保障 }); });6. 性能、成本与最佳实践6.1 性能优化策略视觉测试的耗时主要来自模型API调用。以下策略可以提升速度本地模型部署使用Qwen-VL等开源模型在局域网内自托管。消除网络延迟且无调用次数限制。缓存定位结果对于静态或很少变化的元素如导航栏菜单首次成功定位后可以将坐标缓存起来。下次直接在缓存区域尝试操作失败再调用模型。Midscene的API设计允许这种优化。减少不必要的截图和断言合理安排测试步骤避免每个操作后都进行全屏断言。在关键业务节点页面跳转、表单提交后进行断言即可。并行执行在CI/CD中可以利用多个机器/容器并行运行不同的视觉测试套件。6.2 成本控制使用商业API如豆包Seed、Gemini会产生费用。控制成本的方法精准使用在核心、复杂的业务流程中使用高精度商业模型在简单、稳定的场景使用开源模型或缓存。设置预算与告警在云服务商后台设置每月预算和用量告警。测试数据管理避免在测试中使用真实、敏感的用户数据防止不必要的模型调用泄露信息。6.3 提升测试稳定性的“咒语”工程模型的执行效果很大程度上取决于你如何“描述”指令。这就是“提示词Prompt工程”在测试领域的应用。具体而非抽象“点击那个按钮” - “点击那个蓝色的、写着‘立即购买’的矩形按钮”。使用相对位置当元素没有明显文本时“点击用户名输入框右侧的那个眼睛图标”。结合上下文“在顶部的导航栏中找到并点击‘设置’标签页”。避免歧义如果页面上有多个“提交”按钮要指明是“表单底部的提交按钮”还是“弹窗里的提交按钮”。在Playground中反复试验找到针对你产品UI最有效的指令表述模板并将其固化为团队规范。7. 常见问题与排查指南在实际使用中你可能会遇到以下典型问题问题现象可能原因排查与解决思路aiAct执行失败模型找不到元素1. 指令描述模糊或歧义。2. 界面尚未加载完成。3. 元素在截图时被遮挡如弹窗、动画。4. 模型能力局限。1.查看报告检查失败步骤的截图看模型定位到了哪里。去Playground用同一张图试验不同指令。2.增加等待在操作前使用page.waitForLoadState(networkidle)或自定义等待条件。3.处理动态内容关闭动画或确保操作前遮挡物已消失。4.切换模型尝试使用豆包Seed等更稳健的模型。测试在CI环境中不稳定通过率低1. CI环境屏幕分辨率、缩放比例与本地不同。2. CI环境是headless模式渲染可能与真实浏览器有差异。3. 网络延迟导致截图与操作时机不对。1.统一环境在CI中固定虚拟机的分辨率和缩放为100%。2.使用headed模式在CI中配置headless: false运行需要虚拟帧缓冲区如xvfb。3.增加容错与重试对关键操作和断言封装重试逻辑。Midscene SDK本身也提供了重试参数。桌面端自动化无法操作窗口操作系统权限未授予。macOS进入“系统设置”-“隐私与安全性”-“屏幕录制”/“辅助功能”为你的终端或脚本运行器如node勾选权限并重启应用。Windows确保应用以适当权限运行。移动端测试无法连接设备1. 设备未开启USB调试Android。2. ADB未识别设备。3. iOS设备需要WebDriverAgent签名等复杂配置。1.Androidadb devices确认设备在线。使用scrcpy等工具先确认可投屏。2.iOS建议先从模拟器开始。真机测试需要苹果开发者账号和复杂的配置可参考Midscene文档的iOS专项指南。执行速度太慢每个步骤都调用远程模型API网络往返耗时。1.启用缓存如果框架支持。2.使用本地模型。3.审视测试用例是否每个步骤都需要视觉驱动能否将一系列操作合并到一个aiAct指令中我个人在实际项目中的体会是引入Midscene的最佳策略是“渐进式”。不要试图一夜之间重写所有用例。从一个最让你头疼的、选择器频繁失效的“钉子户”流程开始。用它来验证Midscene在你特定技术栈和业务场景下的效果。你会经历一个从怀疑到惊喜的过程——当看到它成功自动化了一个布满Canvas图表的复杂报表页面时那种解脱感是实实在在的。它确实会带来新的挑战稳定性调优、成本控制但也打开了一扇新的大门让那些曾经被认为“无法自动化”的测试场景成为了可能。