1. 项目概述为什么我们需要视觉AI自动化测试如果你是一名前端开发、测试工程师或者正在构建一个需要频繁回归测试的Web应用那么你一定对UI自动化测试又爱又恨。爱的是它能解放我们的双手让重复的点击、输入、验证工作交给机器恨的是维护这些自动化脚本的成本高得吓人。一个按钮的># 1. 创建项目目录并进入 mkdir midscene-quickstart cd midscene-quickstart # 2. 初始化npm项目一路回车使用默认配置即可 npm init -y # 3. 安装核心依赖Midscene.js 和 Playwright npm install midscene playwright # 4. 安装Playwright的浏览器二进制文件这一步可能需要一些时间 npx playwright install chromium安装过程详解与避坑执行npm install midscene playwright时可能会看到一些关于peer dependencies的警告。这通常是正常的只要最终安装成功即可。Midscene.js 对Playwright的版本有要求安装命令会自动匹配兼容的版本。npx playwright install chromium会下载Chromium浏览器的一个特定版本这个版本与刚安装的Playwright库是严格匹配的确保了API的稳定性。如果你需要Firefox或WebKit可以运行npx playwright install firefox webkit但为了快速上手我们先只安装Chromium。如果下载速度很慢或失败可以尝试设置镜像源或者检查网络连接。这是搭建环境时最常见的“卡点”。3. 编写你的第一个视觉自动化测试脚本环境就绪我们来写一个实实在在的测试用例。假设我们要测试一个经典的TodoMVC应用一个用于演示前端框架的待办事项应用我们的测试场景是打开页面添加一个新的待办事项并验证它出现在列表中。3.1 获取API密钥并配置模型首先你需要去 Google AI Studio 注册并创建一个API密钥。这个过程是免费的并且会提供一定的免费调用额度。拿到密钥后我们不在代码中硬编码它而是通过环境变量来传递这是更安全、更灵活的做法。在项目根目录创建一个名为.env的文件# .env 文件 GEMINI_API_KEY你的_Google_AI_Studio_API_密钥然后我们需要安装dotenv包来在代码中读取这个文件。npm install dotenv3.2 创建测试脚本文件在项目根目录下创建一个名为first-test.js的文件。我们将一步步填充代码。// first-test.js require(dotenv).config(); // 加载.env文件中的环境变量 const { chromium } require(playwright); const { MidsceneWebAgent } require(midscene); (async () { // 1. 启动浏览器 const browser await chromium.launch({ headless: false, // 设置为true则在后台无界面运行false则会打开浏览器窗口方便调试 slowMo: 500, // 将每个操作放慢500毫秒方便我们观察AI的执行过程 }); const context await browser.newContext(); const page await context.newPage(); // 2. 创建Midscene智能体并配置使用Gemini模型 const agent new MidsceneWebAgent(page, { model: gemini-2.0-flash, // 指定模型 apiKey: process.env.GEMINI_API_KEY, // 从环境变量读取API Key }); try { // 3. 导航到待测试的页面 await page.goto(https://todomvc.com/examples/vue/); // 4. 使用自然语言驱动AI进行操作和断言 console.log(步骤1: 添加待办事项); await agent.aiAct(在输入框里输入“学习Midscene.js”然后按回车); console.log(步骤2: 验证待办事项已添加); const isItemPresent await agent.aiBoolean(列表中是否包含文本“学习Midscene.js”的待办事项); if (isItemPresent) { console.log(✅ 测试通过待办事项“学习Midscene.js”已成功添加。); } else { console.error(❌ 测试失败未找到待办事项。); // 在实际测试框架中这里应该抛出错误 } // 5. (可选) 进行更复杂的操作比如标记完成 console.log(步骤3: 标记为完成); await agent.aiAct(点击“学习Midscene.js”待办事项左侧的复选框将其标记为已完成); const isCompleted await agent.aiBoolean(“学习Midscene.js”这个待办事项看起来是已完成状态吗通常会有删除线); if (isCompleted) { console.log(✅ 待办事项成功标记为完成。); } } catch (error) { console.error(自动化执行过程中出现错误:, error); } finally { // 6. 关闭浏览器释放资源 await browser.close(); } })();3.3 代码逐行解析与核心API说明启动浏览器(chromium.launch)我们以headless: false模式启动这样浏览器的每一步操作我们都看得见对于调试和学习至关重要。slowMo参数是一个非常有用的调试工具它让AI的每次点击、输入之间都有停顿仿佛开启了“子弹时间”让你能看清整个过程。创建Midscene智能体(new MidsceneWebAgent)这是与Midscene.js交互的核心对象。我们将Playwright的page对象传给它并配置模型参数。这里的关键是model字段必须与Midscene.js支持的模型名称一致apiKey从环境变量安全读取。导航(page.goto)这是标准的Playwright操作导航到目标URL。agent.aiAct- 核心行动指令这是最常用的方法。你只需用一句人话描述你想让AI执行的动作。AI会分析当前页面截图定位你描述的元素如“输入框”并执行操作“输入”、“按回车”。你不需要知道这个输入框的CSS选择器是.new-todo。agent.aiBoolean- 视觉查询与断言这个方法用于向AI提问一个关于当前屏幕的是/否问题。它返回一个布尔值。我们用它来验证待办事项是否成功添加到列表。这是一种非常直观的断言方式模仿了人工测试时的检查逻辑。资源清理在finally块中关闭浏览器是一个好习惯确保无论测试成功还是失败都不会有浏览器进程残留。实操心得在编写aiAct的指令时尽量清晰、无歧义。例如“点击登录按钮”就比“点击那个按钮”要好。如果页面上有多个相似元素可以增加上下文如“点击导航栏右侧的登录按钮”。多模态模型的理解能力很强但清晰的指令能获得更稳定、更准确的结果。4. 运行测试与结果分析脚本写好了让我们运行它看看这神奇的5分钟成果。在终端中运行以下命令node first-test.js如果一切配置正确你将看到以下过程一个Chromium浏览器窗口会自动打开并跳转到TodoMVC页面。稍作停顿模型在思考光标会自动移动到页面的输入框并输入“学习Midscene.js”然后按下回车。页面下方会出现一个新的待办事项条目。控制台会打印出“✅ 测试通过...”的消息。接着AI会找到那个新条目左侧的复选框并点击条目文字上会出现删除线。最后浏览器关闭。恭喜你已经成功完成了一次完全由自然语言驱动的视觉UI自动化测试。4.1 理解执行流程与AI的“思考”过程在slowMo的帮助下你能清晰地看到AI的“操作链”截图 - 发送给模型附带你的指令- 模型返回坐标和操作类型 - Midscene.js 驱动鼠标/键盘执行。虽然我们只写了一行aiAct但背后完成的是“定位元素”、“执行操作”等多个子步骤。如果测试失败了怎么办Midscene.js 的一个强大特性是它会生成可视化的执行报告。默认情况下每次aiAct或aiQuery的调用Midscene都会在本地缓存模型的推理结果包括它“看”到了什么决定点击哪里。你可以在项目目录下找到这些缓存文件或者通过配置开启更详细的报告功能这对于调试“为什么AI点错了地方”至关重要。4.2 从脚本到集成测试框架我们刚才写的是一个独立的Node.js脚本。在实际项目中你会希望将Midscene.js集成到专业的测试框架中如Jest、Mocha或Playwright Test。这样做能获得更好的测试生命周期管理、钩子函数beforeEach, afterEach、断言库和并行执行等能力。以Playwright Test为例集成非常简单// tests/visual-test.spec.js const { test, expect } require(playwright/test); const { MidsceneWebAgent } require(midscene); test(使用Midscene添加并完成待办事项, async ({ page }) { const agent new MidsceneWebAgent(page, { model: gemini-2.0-flash, apiKey: process.env.GEMINI_API_KEY, }); await page.goto(https://todomvc.com/examples/vue/); await agent.aiAct(在输入框里输入“集成测试”然后按回车); // 使用Playwright Test的expect进行断言结合Midscene的视觉查询 const isPresent await agent.aiBoolean(列表中是否有“集成测试”); expect(isPresent).toBeTruthy(); });然后使用npx playwright test来运行它。这样你的视觉AI测试就和现有的自动化测试流水线无缝融合了。5. 进阶配置与最佳实践成功运行第一个测试只是开始。要将Midscene.js用于真实项目你需要了解一些关键配置和最佳实践以提升测试的稳定性、速度和成本效益。5.1 模型策略与成本优化直接使用Gemini Flash的API虽然方便但每次调用都需要网络请求并产生费用尽管有免费额度。对于大型测试套件成本和控制力是需要考虑的问题。策略一混合模型策略Midscene.js 允许你配置模型降级策略。例如你可以让简单的“点击”操作使用本地部署的、速度快成本低的轻量模型如UI-TARS而让复杂的“验证整个表单布局”任务使用能力更强的付费模型如Gemini Pro。这需要在创建Agent时进行更详细的配置。策略二充分利用缓存Midscene.js 的规划和定位结果可以被缓存。对于稳定的UI第一次运行后后续相同的操作可以直接使用缓存的结果无需再次调用AI模型速度极快且零成本。你需要确保缓存目录通常是项目下的.midscene文件夹被正确纳入版本管理或CI/CD的缓存机制中。5.2 提升指令的精确性与稳定性自然语言很灵活但也可能带来歧义。以下是编写高质量指令的一些技巧使用明确的指向词优先使用“左上角的”、“红色的”、“带有垃圾桶图标的”等描述而非“那个”。结合上下文如果上一步操作改变了页面状态可以在下一步指令中提及。例如上一步aiAct(‘点击新建按钮’)后下一步可以是aiAct(‘在刚刚弹出的模态框里的名称输入框输入内容’)。分而治之对于复杂任务不要试图用一句超长的指令完成。拆分成多个aiAct步骤就像我们示例中先添加、再标记完成一样。这提高了可读性也便于在失败时定位问题。善用aiQuery获取上下文aiQuery方法可以要求模型返回结构化信息。例如const buttonTexts await agent.aiQuery(‘列出页面上所有按钮的文本内容以数组形式返回’)。这可以用于做更复杂的逻辑判断。5.3 处理动态内容与等待即使对于视觉AI异步加载的内容也是一个挑战。一个按钮可能在截图后0.5秒才出现。Midscene.js 与Playwright的集成很好地解决了这个问题。内置重试机制aiAct和aiQuery内部已经包含了一定的重试逻辑。如果模型在截图中没找到目标它会等待一小段时间后重试截图和识别。结合Playwright等待在关键的网络请求或导航之后可以先用Playwright的原生等待方法确保页面到达稳定状态再调用Midscene。例如await page.click(‘#load-data-button’); await page.waitForResponse(‘**/api/data’); // 等待API响应 await agent.aiAct(‘现在点击表格中的第一行编辑按钮’); // 此时数据已加载表格已渲染5.4 视觉断言的艺术除了aiBooleanMidscene.js 还提供了aiAssert来进行更丰富的视觉断言。例如你可以断言某个元素的视觉状态// 断言错误提示框是可见的并且背景色是红色系的 await agent.aiAssert(‘应该能看到一个红色的错误提示框’); // 如果断言失败测试会在此处抛出错误并附上模型认为的当前屏幕状态描述。视觉断言非常强大它可以验证那些传统基于DOM的断言无法触及的部分比如“图片是否正确加载”、“CSS动画是否生效”、“颜色是否符合设计规范”。你可以将其作为对现有测试断言库的强大补充。6. 常见问题排查与调试技巧在实际使用中你可能会遇到一些问题。这里整理了一份快速排查指南。问题现象可能原因解决方案运行脚本时报错Cannot find module ‘midscene’依赖未正确安装。在项目根目录重新运行npm install。执行aiAct时提示Invalid API Key或模型认证失败。1. API Key未设置或错误。2. 环境变量未加载。3. 模型名称拼写错误。1. 检查.env文件中的KEY是否正确。2. 确认代码中require(‘dotenv’).config()在创建Agent之前执行。3. 核对Midscene.js文档使用正确的模型标识符。AI点击了错误的位置或说找不到元素。1. 指令描述模糊。2. 页面尚未加载完成。3. 模型对于当前UI的理解有偏差。1. 优化指令增加更独特的描述词。2. 在操作前增加page.waitForLoadState(‘networkidle’)或等待特定元素。3. 开启slowMo和详细日志查看AI的推理缓存理解它“看”到了什么。尝试换用不同的模型。测试运行速度很慢。1. 每次操作都调用云端API网络延迟高。2. 没有使用缓存。1. 考虑使用更快的模型如Flash版本或部署本地模型。2. 检查并确保缓存功能已启用且有效。对于不变的操作首次运行后速度会大幅提升。在CI/CD如GitHub Actions中运行失败。1. 无头模式下的截图分辨率或字体与本地不同。2. 环境变量未在CI环境中设置。3. 未安装浏览器。1. 在CI配置中固定浏览器的视窗大小context.newPage({ viewport: { width: 1280, height: 720 } })。2. 在CI的设置中配置GEMINI_API_KEY为保密变量。3. 确保CI流水线中执行了npx playwright install chromium。调试金律打开缓存复盘推理。Midscene.js 默认会将模型的推理过程包括它分析截图后的文本描述和定位框保存在.midscene/cache目录下。当测试行为不符合预期时查看这些缓存文件是定位问题的第一选择。你会看到模型当时“认为”屏幕上有什么以及它为什么决定点击某个坐标。这比盲目猜测有效得多。最后我个人在实际将Midscene.js引入团队项目中的体会是它并非要完全取代传统的基于选择器的自动化测试而是作为一种强大的补充和特定场景的解决方案。对于那些UI变化频繁、富含自定义图形组件如Canvas图表、游戏界面、或者需要验证最终视觉渲染效果的测试场景它的优势是无可比拟的。从今天这5分钟的搭建开始尝试用它来解决一个你当前测试中最“疼”的那个点你会更深刻地感受到视觉驱动自动化带来的改变。