Midscene视觉驱动UI自动化测试：跨平台零代码实践指南

1. 项目概述当UI测试遇上“视觉AI”如果你和我一样在软件开发的泥潭里摸爬滚打过几年一定对UI自动化测试又爱又恨。爱的是它理论上能解放我们重复劳动的双手恨的是维护成本高得吓人——今天写的XPath选择器明天前端改个class名就全挂了测个Canvas图表或者Flutter写的界面传统的基于DOM或无障碍树Accessibility Tree的工具基本束手无策。更别提要覆盖Web、Android、iOS、桌面端等多个平台光是搭建和维护几套不同的测试框架就够喝一壶了。最近一个叫Midscene的开源项目进入了我的视野它提出了一种截然不同的思路视觉驱动。简单说它不关心你的页面底层是什么结构DOM、View Hierarchy它只“看”屏幕截图然后像真人测试一样根据你写的自然语言指令去“操作”和“判断”界面。这个概念听起来很“AI”但Midscene把它做成了一个实实在在、能跑起来的SDK。我花了些时间深度折腾了一下发现它确实有可能改变我们做跨平台UI自动化的游戏规则。这不是又一个“AI画大饼”的工具而是一个已经能解决实际痛点的工程化方案。接下来我就把我从零开始用Midscene搭建一套“零代码”这里指无需编写传统意义上的定位代码驱动的跨平台UI自动化测试方案的经验、踩过的坑和最终效果毫无保留地分享给你。2. 核心思路拆解为什么是“视觉驱动”在深入实操之前我们必须先搞清楚Midscene的底层逻辑这决定了我们后续所有方案设计和问题排查的方向。传统的UI自动化无论是Selenium、Appium还是Playwright其核心都是基于界面元素的抽象描述如ID、XPath、CSS Selector来定位和操作。这套模式有两个天生的“阿喀琉斯之踵”脆弱性前端或客户端UI的任何结构性调整哪怕是重命名一个CSS类都可能导致定位器失效测试用例需要频繁维护。局限性对于没有嵌入语义化信息的元素如图标按钮、游戏界面、Canvas/WebGL渲染的内容、或者无法通过常规手段获取结构树的场景如某些桌面应用、跨域iframe传统工具几乎无能为力。Midscene选择了一条“另类”的道路它完全绕过界面结构直接处理屏幕的视觉信息截图。它的工作流程可以简化为以下三步截图Midscene驱动被测应用Web浏览器、手机模拟器、桌面窗口并捕获当前屏幕图像。视觉理解与规划将截图和你用自然语言描述的指令例如“点击登录按钮”、“检查是否有错误提示弹窗”一起发送给一个多模态大模型如Qwen-VL、GLM-4V。这个模型负责“看懂”图片理解指令并规划出具体的操作步骤如按钮的坐标位置、预期的文本内容。执行与断言Midscene接收模型返回的规划结果将其转化为对应平台的原生操作如鼠标点击、触摸事件、键盘输入并执行。对于断言同样是基于视觉结果进行判断。这种模式带来了几个颠覆性的优势跨平台一致性无论底层是Web、Android、iOS还是Windows桌面对Midscene来说输入都是“一张图”输出都是“一个操作指令”。一套API和脚本逻辑理论上可以覆盖所有平台大大降低了多端测试的复杂度。极强的健壮性只要UI的视觉外观和布局没有发生影响功能判断的巨变比如按钮从蓝色变成红色但位置和文字没变即使内部DOM结构翻天覆地测试用例依然能运行。这直接将维护成本从“代码级”降到了“设计稿级”。能力边界扩展只要是屏幕上能看见的理论上都能操作和验证。这为测试Canvas图表、游戏UI、视频覆盖层等传统盲区提供了可能。当然视觉驱动并非银弹它引入的新挑战我们后面会详细讨论比如对模型能力的依赖、执行速度、以及复杂交互逻辑的稳定性。3. 环境搭建与核心配置实战理解了原理我们开始动手。Midscene的核心是一个Node.js SDK因此环境搭建围绕Node.js生态展开。我的目标是搭建一个能同时测试Web应用和Android App的环境。3.1 基础环境准备首先确保你的开发机满足以下条件Node.js环境推荐使用LTS版本如v20.x。安装后在终端验证node --version npm --version项目初始化创建一个新的目录作为你的测试项目并初始化package.json。mkdir midscene-cross-platform-test cd midscene-cross-platform-test npm init -y安装Midscene核心包npm install midscene这一步会安装Midscene的核心SDK。根据你后续要测试的平台可能还需要安装对应的驱动适配器。3.2 多模态模型配置引擎的“大脑”这是Midscene最核心也最需要仔细配置的部分。模型决定了“看”得准不准、“想”得对不对。Midscene支持多种模型分为云端API和本地部署两大类。方案一使用云端API快速上手推荐新手对于快速验证和原型开发使用云厂商提供的多模态模型API是最方便的。这里以阿里云灵积平台的Qwen2.5-VL模型为例因为它对中文UI的理解和指令跟随能力非常出色且性价比高。获取API Key前往阿里云灵积平台创建账号并获取你的API Key。在项目中配置模型Midscene支持通过环境变量或代码配置模型。我推荐在项目根目录创建.env文件记得加入.gitignore来管理敏感信息。# .env 文件 MIDSCENE_MODEL_PROVIDERalibaba ALIBABA_API_KEYyour_actual_api_key_here ALIBABA_MODELqwen2.5-vl-72b-instruct注意模型名称请务必查阅Midscene官方文档的“模型策略”章节确认其支持的精确模型标识。不同提供商如OpenAI、Google Gemini的配置项不同。在代码中加载配置在你的测试脚本中可以这样初始化一个使用该模型的Agent。// test-with-env.js import { Agent } from midscene; import * as dotenv from dotenv; dotenv.config(); // 加载 .env 文件中的环境变量 // 初始化一个Web测试的Agent模型配置会自动从环境变量读取 const agent await Agent.for(web).launch();方案二本地部署模型追求可控与隐私如果你的测试涉及敏感数据或希望获得更稳定的响应速度不受网络波动影响可以考虑在本地部署开源模型。Qwen2.5-VL或UI-TARS是很好的选择。这需要一定的GPU资源。部署模型服务使用Ollama、vLLM或ModelScope等工具在本地服务器部署模型。例如用Ollama运行Qwen2.5-VLollama run qwen2.5-vl:7b运行后模型会提供一个本地的API端点通常是http://localhost:11434。配置Midscene使用本地模型在.env文件中或代码中指定。MIDSCENE_MODEL_PROVIDERopenai-compatible OPENAI_COMPATIBLE_BASE_URLhttp://localhost:11434/v1 OPENAI_COMPATIBLE_API_KEYollama # 如果不需要密钥可以填任意值 OPENAI_COMPATIBLE_MODELqwen2.5-vl:7b实操心得模型选择初期验证无脑用阿里云Qwen2.5-VL的API速度快效果稳定成本可控按token计费测试脚本消耗极低。深度使用如果测试用例量大、固定考虑本地部署。7B参数的模型在RTX 4060级别的显卡上就能流畅运行长期来看更经济且数据不出内网。避坑指南不同模型对同一指令的理解可能有差异。建议为你的核心用例如“点击那个圆形的红色图标”编写一小段基准测试对比不同模型的成功率再做出选择。3.3 目标平台环境搭建Midscene通过不同的“驱动”来连接各类平台。你需要根据测试目标安装对应的工具。对于Web测试Midscene底层基于Playwright或Puppeteer。安装Playwright及其浏览器npm install playwright npx playwright install chromium在代码中你可以通过Agent.for(web)来创建Web测试代理它会自动管理浏览器实例。对于Android测试这是跨平台测试的关键一环。你需要Android SDK确保adb(Android Debug Bridge) 命令可用。通常安装Android Studio或命令行工具即可。连接设备通过USB连接真机或启动Android模拟器如Android Studio自带的AVD。验证连接在终端运行adb devices应能看到你的设备列表。安装Midscene Android驱动Midscene可能需要额外的本地依赖来高效截图和注入事件。根据其文档可能需要运行npx midscene android setup来完成环境配置。对于iOS测试需要在macOS环境下并安装Xcode和相关的开发工具链。配置相对复杂涉及WebDriverAgent的编译和签名。如果你是Windows/Linux用户暂时无法进行iOS真机测试可以考虑使用云测平台提供的iOS设备。配置多平台Agent的示例代码import { Agent } from midscene; // Web Agent const webAgent await Agent.for(web).launch({ headless: false // 显示浏览器方便调试 }); // Android Agent const androidAgent await Agent.for(android).launch({ deviceId: 你的设备序列号, // 通过 adb devices 获取 // 其他配置如应用包名等 }); // 使用完毕后记得关闭agent以释放资源 await webAgent.close(); await androidAgent.close();4. 从零编写你的第一个“零代码”测试用例环境配好了我们来写点真正的测试。所谓“零代码”并不是完全不用写代码而是指无需编写繁琐、脆弱的元素定位代码XPath/CSS Selector。测试逻辑依然需要用结构化的方式描述Midscene提供了YAML和JavaScript两种风格。4.1 YAML脚本风格像写清单一样写测试YAML格式非常适合编写线性的、描述性的测试流程可读性极高甚至可以让产品经理或QA同学直接参与编写。假设我们要测试一个简单的登录场景打开一个Web登录页输入用户名密码点击登录验证登录成功后的跳转。创建一个文件test-login.yamlname: Web应用登录功能测试 description: 验证用户能使用正确凭据登录 steps: - name: 导航到登录页面 action: aiAct args: [打开浏览器访问 https://example.com/login] - name: 输入用户名 action: aiAct args: [在用户名输入框中填入 ‘testuser‘] - name: “输入密码” action: aiAct args: [在密码输入框中填入 ‘password123‘] - name: “点击登录按钮” action: aiAct args: [点击‘登录’按钮] - name: “验证登录成功” action: aiAssert args: [检查页面是否显示‘欢迎回来testuser’或类似的成功提示信息] expected: true运行这个YAML脚本非常简单Midscene提供了命令行工具npx midscene run ./test-login.yaml --platform webMidscene会依次执行每一步打开浏览器、访问页面、模型会“看到”页面找到用户名输入框并输入文本……整个过程你不需要知道输入框的ID是什么按钮的CSS类是什么。4.2 JavaScript SDK风格更灵活更强大对于更复杂的测试逻辑如循环、条件判断、数据驱动使用JavaScript SDK是更专业的选择。它提供了完整的编程能力。创建文件test-login.jsimport { Agent } from midscene; import * as dotenv from dotenv; dotenv.config(); (async () { console.log(启动Web测试Agent...); const agent await Agent.for(web).launch({ headless: false, // 显示界面便于观察 viewport: { width: 1280, height: 720 } }); try { // 步骤1导航 await agent.aiAct(打开浏览器访问 https://example.com/login); await agent.waitForPageIdle(); // 等待页面稳定 // 步骤2查询并输入 - 这里展示更精细的控制 // aiQuery 可以返回模型“看到”的信息 const usernamePlaceholder await agent.aiQuery(字符串用户名输入框的占位符文本是什么); console.log(模型识别到用户名输入框提示语是${usernamePlaceholder}); // 使用aiAct执行操作 await agent.aiAct(在提示语为“${usernamePlaceholder}”的输入框里输入“testuser”); // 步骤3输入密码 await agent.aiAct(在密码输入框里输入“password123”); // 步骤4点击登录 await agent.aiAct(点击“登录”按钮); await agent.waitForPageIdle(); // 等待登录请求完成和页面跳转/刷新 // 步骤5断言 - 使用aiBoolean进行布尔判断 const loginSuccess await agent.aiBoolean(当前页面是否显示了欢迎用户的文本或者登录成功的提示); if (loginSuccess) { console.log(✅ 登录成功断言通过); } else { // 失败时可以结合aiQuery获取更多上下文信息辅助调试 const pageIndicator await agent.aiQuery(当前页面最顶部或最显眼的标题或文本是什么); console.error(❌ 登录失败。当前页面关键标识是“${pageIndicator}”); throw new Error(登录成功断言失败); } // 步骤6可选更复杂的视觉断言 // 检查某个特定区域的元素是否存在且状态正确 const isProfileIconVisible await agent.aiBoolean(在页面右上角是否能看到一个代表用户头像或资料的图标); console.log(用户头像图标可见${isProfileIconVisible}); } catch (error) { console.error(测试执行失败, error); // Midscene会自动生成可视化的测试报告包含每一步的截图和模型决策 const reportPath await agent.saveReport(login-test-failure); console.log(详细错误报告已生成至${reportPath}); } finally { await agent.close(); console.log(测试结束资源已释放。); } })();运行这个脚本node test-login.js两种风格如何选择YAML适合简单、线性的端到端E2E场景测试以及作为与AI协作的“自然语言需求描述”。你可以让大模型直接将需求转化为YAML测试脚本。JavaScript适合需要复杂逻辑、集成到现有CI/CD流水线、进行数据驱动测试、或者需要调用其他Node.js库如读取测试数据文件的严肃测试工程。5. 构建跨平台测试套件的最佳实践单一平台的测试只是开始Midscene的真正威力在于用一套逻辑覆盖多端。我们的目标是同一份业务测试逻辑能在Web、Android、iOS上运行。这需要一些架构设计。5.1 抽象“页面对象”与“操作指令”虽然Midscene不需要定位器但我们仍然需要抽象以应对不同平台UI的细微差异。我们抽象的不是元素而是**“意图”**。例如“登录”这个意图在不同平台上的UI可能不同Web端一个大的“登录”按钮。App端屏幕底部的一个“登录”Tab。我们可以创建一个简单的“指令映射”配置// instructions-map.js export const platformInstructions { login: { web: “点击页面中央最大的那个‘登录’按钮” android: “点击屏幕底部导航栏的‘登录’选项卡” ios: “点击底部标签栏的‘登录’图标” }, inputUsername: { web: “在用户名输入框里输入‘{username}’” android: “在第一个文本输入框也就是用户名框里输入‘{username}’” ios: “在顶部第一个文本字段输入‘{username}’” } // ... 更多指令 };5.2 编写平台无关的测试流程然后我们编写一个平台无关的测试函数// cross-platform-login.test.js import { Agent } from midscene; import { platformInstructions } from ./instructions-map.js; async function testLoginAcrossPlatform(platform, deviceConfig) { console.log(\n 开始在 ${platform.toUpperCase()} 平台执行登录测试 ); const agent await Agent.for(platform).launch(deviceConfig); try { // 1. 启动App或打开网页 (指令可能不同这里简化) if (platform web) { await agent.aiAct(打开浏览器访问 https://m.example.com/login); } else { await agent.aiAct(从手机桌面找到并打开我们的应用); await agent.aiAct(在应用首页找到并进入登录页面); } await agent.waitForPageIdle(); // 2. 输入用户名使用平台特定指令 const usernameInstruction platformInstructions.inputUsername[platform].replace({username}, testuser); await agent.aiAct(usernameInstruction); // 3. 输入密码假设指令通用 await agent.aiAct(在密码输入框里输入“password123”); // 4. 执行登录使用平台特定指令 await agent.aiAct(platformInstructions.login[platform]); await agent.waitForPageIdle(); // 5. 通用断言检查登录后是否跳离了登录页面 const stillOnLoginPage await agent.aiBoolean(当前页面是否还有“用户名”和“密码”输入框); if (stillOnLoginPage) { throw new Error(登录后似乎仍停留在登录页面); } console.log(✅ ${platform.toUpperCase()} 平台登录流程执行通过); } catch (error) { console.error(❌ ${platform.toUpperCase()} 平台测试失败, error.message); await agent.saveReport(failure-${platform}-login); throw error; // 重新抛出让上层测试运行器知晓 } finally { await agent.close(); } } // 在主函数中依次或并行运行多平台测试 (async () { const configs [ { platform: web, deviceConfig: { headless: true } }, { platform: android, deviceConfig: { deviceId: emulator-5554 } }, // { platform: ios, deviceConfig: { ... } } // iOS配置 ]; for (const config of configs) { try { await testLoginAcrossPlatform(config.platform, config.deviceConfig); } catch (e) { // 记录失败但继续测试其他平台 console.error(平台 ${config.platform} 测试中止。); } } })();5.3 集成到CI/CD流水线要让自动化测试产生价值必须将其集成到持续集成流程中。以GitHub Actions为例可以这样配置# .github/workflows/ui-test.yml name: Cross-Platform UI Tests on: [push, pull_request] jobs: test: runs-on: ubuntu-latest strategy: matrix: platform: [web, android] # 矩阵运行测试多个平台 steps: - uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 - name: Install dependencies run: npm ci - name: Setup Android Emulator (for android job) if: matrix.platform android uses: reactivecircus/android-emulator-runnerv2 with: api-level: 33 target: google_apis arch: x86_64 profile: Nexus 6 script: echo “Emulator is ready” - name: Install Playwright Browsers (for web job) if: matrix.platform web run: npx playwright install chromium - name: Run Midscene Tests env: MIDSCENE_MODEL_PROVIDER: ${{ secrets.MIDSCENE_MODEL_PROVIDER }} ALIBABA_API_KEY: ${{ secrets.ALIBABA_API_KEY }} ALIBABA_MODEL: qwen2.5-vl-72b-instruct run: | if [ ${{ matrix.platform }} android ]; then # 等待模拟器完全启动 adb wait-for-device # 安装被测APK (假设已放在项目根目录) adb install -t app-debug.apk fi # 运行对应平台的测试套件 node run-tests-${{ matrix.platform }}.js - name: Upload Test Reports if: always() # 无论成功失败都上传报告 uses: actions/upload-artifactv4 with: name: ui-test-reports-${{ matrix.platform }} path: | **/midscene-report-* **/screenshots/这个工作流会分别在Web和Android模拟器上运行你的Midscene测试脚本并将生成的视觉报告保存为制品供后续查看。6. 避坑指南与效能优化在实际项目中大规模使用Midscene你会遇到一些挑战。以下是我总结的常见问题和优化策略。6.1 稳定性与准确性提升视觉AI模型并非100%可靠尤其是在复杂、动态或元素密集的界面上。问题1模型“找不到”或“点错”元素。优化指令指令要具体、唯一、包含上下文。避免“点击按钮”而要说“点击蓝色背景、写着‘提交’文字的矩形按钮”。可以引用附近的其他稳定元素作为锚点如“在‘用户名’标签右边的输入框里输入”。使用aiQuery预验证在关键操作前先用aiQuery询问模型“你能看到……吗”根据返回信息决定后续步骤增加脚本的鲁棒性。启用重试与超时Midscene的aiAct等方法可以配置重试策略。await agent.aiAct(点击保存按钮, { retry: 3, // 重试3次 timeout: 30000 // 超时30秒 });问题2页面状态未稳定导致操作失败。强制等待与智能等待在关键操作如跳转、弹窗后使用agent.waitForPageIdle()或自定义的等待逻辑如等待某个特定元素出现。结合传统等待对于已知的网络请求可以结合Playwright的page.waitForResponse()或page.waitForSelector()即使不用于操作仅用于判断状态来确保页面就绪。6.2 执行速度与成本控制调用大模型API有延迟和成本。策略1缓存AI规划结果。Midscene支持缓存功能。对于不变的界面和操作第一次运行后的规划结果如图片中的元素坐标会被缓存后续运行直接使用缓存极大提升速度并降低API调用。const agent await Agent.for(web).launch({ cache: { enable: true, dir: ./.midscene-cache // 缓存目录 } });策略2混合模式。对于极其稳定、高频操作的元素如主导航栏可以首次用Midscene识别并获取其稳定特征如图像特征或相对布局后续测试中可以尝试用更快的图像模板匹配OpenCV或结合少量稳定的无障碍树信息来定位作为对纯视觉方案的补充。Midscene本身也提供了相关API的扩展可能性。策略3选择合适的模型。在CI流水线中可以使用响应速度更快、成本更低的模型如gemini-1.5-flash在需要高精度调试的本地运行中再切换到能力更强的模型如qwen2.5-vl-72b。6.3 测试报告与调试测试失败时清晰的报告至关重要。Midscene默认会生成HTML报告包含每一步的屏幕截图、模型接收的指令、模型的“思考”过程如果模型支持和执行结果。主动保存报告在测试用例的catch块或afterEach钩子中调用agent.saveReport(‘test-case-name’)。解读报告查看报告时重点关注模型失败的那一步的截图和它的“思考”。是没找到元素还是理解错了指令这能帮你优化指令或发现UI设计上的歧义。与现有测试框架集成你可以将Midscene的Agent集成到Jest、Mocha、Vitest等测试框架中利用框架的断言库、生命周期钩子和报告系统获得更熟悉的开发体验。7. 总结与展望这不是未来这是现在经过这一番深度实践我的结论是Midscene所代表的“视觉驱动”的UI自动化测试已经不再是概念验证而是能够解决特定生产痛点的实用工具。它特别适合以下场景跨平台UI一致性验证用一套脚本快速验证同一个功能在Web、Android、iOS上的表现是否一致。对Canvas、游戏、视频等富媒体界面的测试这是它的“杀手锏”传统工具难以触及的领域。快速原型和探索性测试当你面对一个全新的、没有测试积累的应用时用自然语言快速编写测试脚本效率极高。应对频繁的UI重构当你的前端技术栈变动频繁或者处于快速迭代期维护传统自动化脚本的成本高于收益时Midscene能提供一种更稳定的测试方式。当然它并非要完全取代传统的基于结构的自动化测试。后者在执行速度、精确度、复杂逻辑编排上仍有巨大优势。一个理想的测试策略可能是“混合模式”对核心的、稳定的业务流程使用传统自动化保证速度和精准对UI变化频繁的模块、跨平台验证、以及视觉回归测试引入Midscene作为补充。最后分享一个我个人的小技巧在编写Midscene指令时我发现自己仿佛在教一个刚来的实习生如何测试。这个过程反过来也促使我思考我们的UI设计是否足够清晰、直观如果一个智能体都无法从视觉上明确理解如何操作那么真实用户是否也会感到困惑从这个角度看Midscene不仅是一个测试工具更是一面审视产品本身可用性的镜子。