5分钟上手Midscene.js：基于视觉AI的UI自动化测试实践指南

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 dotenv

3.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说明

1. 启动浏览器(chromium.launch)：我们以headless: false模式启动，这样浏览器的每一步操作我们都看得见，对于调试和学习至关重要。slowMo参数是一个非常有用的调试工具，它让AI的每次点击、输入之间都有停顿，仿佛开启了“子弹时间”，让你能看清整个过程。
2. 创建Midscene智能体(new MidsceneWebAgent)：这是与Midscene.js交互的核心对象。我们将Playwright的page对象传给它，并配置模型参数。这里的关键是model字段必须与Midscene.js支持的模型名称一致，apiKey从环境变量安全读取。
3. 导航(page.goto)：这是标准的Playwright操作，导航到目标URL。
4. agent.aiAct- 核心行动指令：这是最常用的方法。你只需用一句人话描述你想让AI执行的动作。AI会分析当前页面截图，定位你描述的元素（如“输入框”），并执行操作（“输入”、“按回车”）。你不需要知道这个输入框的CSS选择器是.new-todo。
5. agent.aiBoolean- 视觉查询与断言：这个方法用于向AI提问一个关于当前屏幕的是/否问题。它返回一个布尔值。我们用它来验证待办事项是否成功添加到列表。这是一种非常直观的断言方式，模仿了人工测试时的检查逻辑。
6. 资源清理：在finally块中关闭浏览器是一个好习惯，确保无论测试成功还是失败，都不会有浏览器进程残留。

实操心得：在编写aiAct的指令时，尽量清晰、无歧义。例如，“点击登录按钮”就比“点击那个按钮”要好。如果页面上有多个相似元素，可以增加上下文，如“点击导航栏右侧的登录按钮”。多模态模型的理解能力很强，但清晰的指令能获得更稳定、更准确的结果。

4. 运行测试与结果分析

脚本写好了，让我们运行它，看看这神奇的5分钟成果。

在终端中，运行以下命令：

node first-test.js

如果一切配置正确，你将看到以下过程：

1. 一个Chromium浏览器窗口会自动打开，并跳转到TodoMVC页面。
2. 稍作停顿（模型在思考），光标会自动移动到页面的输入框，并输入“学习Midscene.js”，然后按下回车。
3. 页面下方会出现一个新的待办事项条目。
4. 控制台会打印出“✅ 测试通过！...”的消息。
5. 接着，AI会找到那个新条目左侧的复选框并点击，条目文字上会出现删除线。
6. 最后，浏览器关闭。

恭喜！你已经成功完成了一次完全由自然语言驱动的视觉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 视觉断言的艺术

除了aiBoolean，Midscene.js 还提供了aiAssert来进行更丰富的视觉断言。例如，你可以断言某个元素的视觉状态：

// 断言错误提示框是可见的，并且背景色是红色系的 await agent.aiAssert(‘应该能看到一个红色的错误提示框’); // 如果断言失败，测试会在此处抛出错误，并附上模型认为的当前屏幕状态描述。

视觉断言非常强大，它可以验证那些传统基于DOM的断言无法触及的部分，比如“图片是否正确加载”、“CSS动画是否生效”、“颜色是否符合设计规范”。你可以将其作为对现有测试断言库的强大补充。

6. 常见问题排查与调试技巧

在实际使用中，你可能会遇到一些问题。这里整理了一份快速排查指南。

调试金律：打开缓存，复盘推理。Midscene.js 默认会将模型的推理过程（包括它分析截图后的文本描述和定位框）保存在.midscene/cache目录下。当测试行为不符合预期时，查看这些缓存文件是定位问题的第一选择。你会看到模型当时“认为”屏幕上有什么，以及它为什么决定点击某个坐标。这比盲目猜测有效得多。

最后，我个人在实际将Midscene.js引入团队项目中的体会是，它并非要完全取代传统的基于选择器的自动化测试，而是作为一种强大的补充和特定场景的解决方案。对于那些UI变化频繁、富含自定义图形组件（如Canvas图表、游戏界面）、或者需要验证最终视觉渲染效果的测试场景，它的优势是无可比拟的。从今天这5分钟的搭建开始，尝试用它来解决一个你当前测试中最“疼”的那个点，你会更深刻地感受到视觉驱动自动化带来的改变。