Midscene.js介绍和使用
由于课程任务的需要，本人去寻找了 AI + 软件测试的相关应用，发现了 Midscene 这一便利的 UI 自动化测试工具。本篇博客主要对 Midscene 作了介绍，也给出了本人在使用 Midscene 过程中遇到的问题及摸索到的解决方案。
Midscene.js 是一个开源的基于多模态大型语言模型的 UI 自动化测试工具，它是由字节的 web-infra 团队开发。它能够智能地“解析”用户界面并自动执行所需操作，从而简化端到端（e2e）测试流程。借助多模态大模型，Midscene 使测试人员可以用自然语言描述测试步骤，从而显著降低了编写测试脚本的难度。无论是查找页面元素、进行交互操作还是确认页面状态，Midscene 都能通过解读自然语言指令来高效完成这些任务。
快速体验
Midscene 的一大亮点是它集成了浏览器插件形式，以此能快速体验其核心功能。我们能在 Chrome 浏览器的拓展商店轻松找到它。
Midscene 的浏览器插件形式如图所示：
要使用 Midscene 拓展，我们需要配置插件环境，这要求我们配置相应的大模型API。Midscene 默认集成了 OpenAI SDK 调用 AI 服务。但我们也可以使用其他兼容此类接口的模型服务。因为 OpenAI 已经不向我国提供服务了，我们需要选择其他的大模型。官方教程中也给出了许多其他模型的配置示例，这里我用了阿里云的qwen-vl-max-latest模型，新用户有一定的免费额度。
Midscene 主要提供了三种AI执行方法：交互, 提取和断言。
-
交互 - 用
.ai或.aiAction方法描述步骤并执行交互。你可以在 Action 栏中用自然语言输入想要让 AI 执行的操作。 -
提取 - 用
.aiQuery从 UI 中“理解”并提取数据，返回值是 JSON 格式，你可以尽情描述想要的数据结构。你可以在 Query 栏中用自然语言输入你想让 AI 在当前页面提取的信息。下图使用了Midscene 的 Query 功能提取了北京未来五天的最高温和最低温的 json 格式数据。
-
断言 - 用
.aiAssert来执行断言。在 Assert 栏中用自然语言输入 AI 需要执行的对于当前页面的断言。
通过Midscene浏览器插件相信你可以很快地掌握和理解Midscene的基本用法了。
Midscene运行报告
Midscene 在运行完毕后会生成一份可视化报告，在这份报告中我们可以观察 AI 的思考过程，回顾动画回放，看到每一步的参数和输出信息。此外，报告中还集成了一个 Playground ，你可以在报告中重新运行 Prompt 并调试，进一步提升测试的效率和准确性。
Yaml自动化脚本的使用
插件虽然很方便，但如果要执行一系列操作，AI 模型就需要通过 planning 这样一个过程,这在浏览器插件中很难实现，浏览器插件适用于单条指令的理解和执行。因此我们可以选择将 Midscene 集成到代码中。
Midscene 提供了一种基于 .yaml 文件的自动化测试方法，这有助于开发者专注于脚本本身，而不是测试框架，因为有些开发者编写脚本的目的只是为了一些简单的测试，比如检查某些内容是否出现，或者验证某个关键用户路径是否可用等。
首先我们需要配置大模型 API 的环境变量，官网的配置命令如下，这应该是 Linux 操作系统的配置方法：
# 更新为你自己的 Key export OPENAI_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"
Windows 系统网上有如下几种配置方法：
1.我们可以选择在系统属性中配置环境变量，因为我使用的是阿里云的qwen-vl-max-latest模型，环境配置官网命令如下：
export OPENAI_API_KEY="sk-..." export OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" export MIDSCENE_MODEL_NAME="qwen-vl-max-latest"
将变量名和变量值对应即可：
2.在命令行（cmd）中添加环境变量：
# 用您的 OPENAI API-KEY 代替 YOUR_OPENAI-API-KEY # 临时性环境变量 set OPENAI_API_KEY="YOUR_OPENAI-API-KEY" # 永久性环境变量 setx OPENAI_API_KEY="YOUR_OPENAI-API-KEY" # 检查环境变量是否生效 echo %OPENAI_API_KEY%
- PowerShell 中添加环境变量：
# 用您的 OPENAI API-KEY 代替 YOUR_OPENAI-API-KEY $env:OPENAI_API_KEY="YOUR_OPENAI-API-KEY" # 检查环境变量是否生效 echo %OPENAI_API_KEY%
可能因为我用的不是 openai 的 API，如上方法在我尝试添加阿里云的qwen-vl-max-latest模型之后程序运行仍然报错：
官网还提到了另一种方法，用 .env 文件存储配置，Midscene 命令行工具在运行 yaml 脚本时会自动加载它，因此我在项目根目录下新建了一个 .env 文件，添加了模型的相关配置。
之后全局安装 @midscene/cli
npm i -g @midscene/cli # 或在项目中安装 npm i @midscene/cli --save-dev
我这边测试的脚本代码是官方案例
target: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 "今日天气" - sleep: 3000 - aiAssert: 结果显示天气信息
其中 target 部分可以定义任务的基本信息，包括访问的网址、浏览器视口角度等等；
tasks 部分是一个数组，定义了脚本执行的步骤。可执行三种方法：交互（.ai, .aiAction), 提取 (.aiQuery), 断言 (.aiAssert)。
之后在命令行中运行脚本
midscene ./bing-search.yaml # 或者如果你在项目中安装了 midscene npx midscene ./bing-search.yaml
运行结果：
可以看到 Midscene 会将运行报告存储到项目下的 midscene_run/report 文件中，打开报告的 html 文件：
Chrome 插件的桥接模式（Bridge Mode）
桥接模式是 Midscene 浏览器插件的另一大功能，这让我们能够用本地脚本控制桌面版本的谷歌浏览器。使用桌面版本的谷歌浏览器可以让我们复用已有的 cookie、插件、页面状态等，从而使用自动化脚本与网页互动。
使用桥接模式需要安装依赖
npm install @midscene/web tsx --save-dev
在测试这一功能时我使用的是 TypeScript 脚本，发现在项目下单纯加个 .env文件依旧会报模型服务的错误。最后我的解决方法是采用 Dotenv ，Dotenv 是一个零依赖的 npm 包，它用于将环境变量从 .env 文件加载到环境变量 process.env 中。
# 安装 dotenv npm install dotenv --save
我们仍然需要在项目根目录下创建 .env 文件，并添加相关配置，但不需要在每一行前都添加 export。
OPENAI_API_KEY="sk-..." OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" MIDSCENE_MODEL_NAME="qwen-vl-max-latest"
然后再脚本中导入 dotenv 模块即可：
import { AgentOverChromeBridge } from "@midscene/web/bridge-mode"; import * as dotenv from 'dotenv'; // 导入dotenv dotenv.config(); const sleep = (ms) => new Promise((r) => setTimeout(r, ms)); Promise.resolve( (async () => { const agent = new AgentOverChromeBridge(); // 这个方法将连接到你的桌面 Chrome 的新标签页 // 记得启动你的 Chrome 插件，并点击 'allow connection' 按钮。否则你会得到一个 timeout 错误 await agent.connectNewTabWithUrl("https://www.bing.com"); // 这些方法与普通 Midscene agent 相同 await agent.ai('type "AI 101" and hit Enter'); await sleep(3000); await agent.aiAssert("there are some search results"); await agent.destroy(); })() );
之后运行脚本
tsx demo-new-tab.ts
将 Midscene 插件的桥接模式打开：
之后我们就会发现浏览器会打开一个新页面执行测试操作，脚本运行和打开 Midscene 插件的桥接模式没有顺序要求。
再 YAML 自动化脚本中也可以使用桥接模式，配置 target 中的 bridgeMode 属性即可。如果想要使用当前标签页，设置为 currentTab，否则设置为 newTabWithUrl。
target: url: https://www.bing.com + bridgeMode: newTabWithUrl tasks:
运行脚本并启动 Chrome 插件，并点击 ‘Allow connection’ 按钮。
midscene ./bing.yaml
Puppeteer 的集成使用
Puppeteer 是一个 Node.js 库，可以在 Python 中使用。它通过 DevTools 协议控制 Chrome 或Chromium，可以用它来自动化几乎所有的浏览器操作，比如点击、滚动、填写表单等等。感觉和我之前使用过的 UI 自动化工具 Selenium 很像。
Puppeteer 通过集成 Midscene，就不需要手动获取网页的元素属性值。通过大模型的自然语言处理能力，自动化测试变得更加方便。
首先我们需要安装依赖
npm install @midscene/web puppeteer tsx --save-dev
编写 ts 脚本：
import puppeteer from "puppeteer"; import { PuppeteerAgent } from "@midscene/web/puppeteer"; import * as dotenv from 'dotenv'; dotenv.config(); // console.log(process.env.OPENAI_API_KEY); const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); Promise.resolve( (async () => { const browser = await puppeteer.launch({ headless: false, // here we use headed mode to help debug }); const page = await browser.newPage(); await page.setViewport({ width: 1280, height: 800, deviceScaleFactor: 1, }); await page.goto("https://www.ebay.com"); await sleep(5000); // 初始化 Midscene agent const mid = new PuppeteerAgent(page); // 执行搜索 await mid.aiAction('在搜索框输入 "Headphones" ，敲回车'); await sleep(5000); // 理解页面，提取数据 const items = await mid.aiQuery( '{itemTitle: string, price: Number}[], 找到列表里的商品标题和价格', ); console.log("耳机商品信息", items); // 用 AI 断言 await mid.aiAssert("界面左侧有类目筛选功能"); await browser.close(); })() );
运行脚本
npx tsx demo.ts
运行结果如下，可以看到命令行中打印出了耳机的商品信息
结语
Midscene 还有许多功能，它也能够集成到 PlayWright，还具有 AI 缓存能力。更多的使用教程可以查看官方文档：https://midscenejs.com/zh/index.html。总体而言 Midscene 是一款很方便的 AI + UI 自动化测试工具，适用于多种自动化测试场景。
