Midscene.js - AI驱动，带来全新UI自动化体验（安装配置篇）

Midscene.js安装配置初体验（先让程序运行起来）

前言

看了很多网上关于Midscene.js工具的文章，大多都是一开始就介绍如何使用该工具，都默认读者都懂得如何安装配置该工具，因为该工具不像下载app应用一样简单，安排配置还是有些麻烦的。

本文就从0开始，讲解如何安装配置Midscene.js，可谓是作者亲身实践的保姆级教程，希望就算是从没做过UI自动化的测试小白也能按照该文章的步骤轻松配置并能使用该工具。

一、Midscene.js 介绍

1. 基本介绍

Midscene.js 是字节跳动开源的 AI 操作助手，适用于Web、移动端的自动化测试。

它是基于多模态大语言模型，能让测试人员使用自然语言控制页面、执行断言以及提取 JSON 格式的数据。

相比传统的UI自动化测试工具Selinium等采用元素定位方式，而且跟系统有较强的耦合性，而Midscene.js通过自然语言交互，极大降低了自动化测试门槛，非专业编程人员也能轻松开展 UI 自动化测试工作。

Homepage：https://midscenejs.com
Github：https://github.com/web-infra-dev/midscene

2. 支持的模型

多模态 LLM 模型：如 gpt-4o
视觉语言模型：如 Qwen2.5-VL、Doubao-1.5-thinking-vision-pro、gemini-2.5-pro、UI-TARS
推荐：使用视觉语言模型进行 UI 自动化。

3. 功能特性

（1）用自然语言编写自动化脚本

描述目标和步骤，Midscene 会规划和操作用户界面
脚本编写格式：可使用 Javascript SDK 或 YAML 格式

（2）支持的自动化场景

网页自动化：可与 Puppeteer 集成、与 Playwright 集成，或使用桥接模式控制桌面浏览器
Android 自动化：使用 Javascript SDK 配合 adb 控制本地 Android 设备
iOS 自动化：使用 Javascript SDK 配合 WebDriverAgent 控制本地 iOS 设备

4. 环境依赖

需要安装Node.js
准备大模型API KEY
配置大模型参数到环境变量
安装Midscene.js

二、Node.js 安装配置

1. Node.js 简介

性质：开源、跨平台的 JavaScript 运行环境
核心：在浏览器外部运行 V8 JavaScript 引擎（Google Chrome 核心），性能高
包管理器：npm（Node.js 的标准软件包管理器，用于安装和管理项目依赖包）

2. Node.js 下载与安装（Windows 系统）

（1）下载并安装

官网地址：https://nodejs.org/en/download
选择版本：推荐下载 LTS 版本（如 v22.20.0），可选择 Windows Installer（.msi）或 Standalone Binary（.zip）格式

（2）安装验证

打开 cmd 命令行工具
输入命令：node -v
验证结果：若返回版本信息（如 v22.20.0），则安装成功；未返回则尝试重新安装

3. 配置npm为国内镜像源

（1）配置原因

提高中国大陆地区用户的下载速度，减少与国际服务器的物理距离

（2）常用国内镜像源

淘宝 npm 镜像：https://registry.npm.taobao.org
华为云 npm 镜像：https://repo.huaweicloud.com
npm 社区镜像：https://registry.npmmirror.com/

（3）配置方式

临时使用

（当前会话有效）：

npm config set registry https://registry.npm.taobao.org

永久使用（全局默认）：

npm config set registry https://registry.npm.taobao.org --global

（4）配置验证

命令：npm config get registry
验证结果：返回配置好的镜像源https://registry.npm.taobao.org，则配置成功

三、Midscene.js 安装与配置

1. Midscene.js 安装

（1）安装命令

打开 cmd，通过npm执行全局安装命令：npm i -g @midscene/cli
说明：安装过程可能较慢，需耐心等待

（2）安装验证

命令：midscene --version
验证结果：若返回版本信息（如 0.29.6），则安装成功

查看帮助：输入midscene --help可了解更多命令行参数

2. 大模型配置

（1）模型选择原则

Midscene 默认集成 OpenAI SDK 调用 AI 服务，支持兼容该接口的所有模型服务。但OpenAI在国内如果不开启VPN是无法访问的，所以推荐使用国内的大模型：阿里通义千问大模型、豆包大模型（参考官网介绍：https://midscenejs.com/zh/choose-a-model.html）

（2）已适配的模型类型

|------------------|----------------------------------|----------------|-----------------------------------------|
| 模型类型 | 特点 | 适用场景 | 包含模型示例 |
| 视觉语言模型（VL 模型，推荐） | 可理解文本和图像输入，能定位页面目标元素坐标，复杂场景更可靠高效 | 任何类型界面的 UI 自动化 | 豆包系列视觉语言模型、千问 VL、Genini-2.5-Pro、UI-TARS |
| LLM 模型 | 可理解文本和图像输入 | 仅 Web 自动化 | GPT-4o 等 |

（3）获取 API KEY

以阿里通义千问大模型为例，打开阿里云百炼地址https://bailian.console.aliyun.com/#/home，先注册自己的个人账户。

点击阿里云百炼网址的"API 参考"页签，进入指导文档:

按照文档的说明，我们在密钥管理中，创建1个自己的KEY，创建后如下：

点击右上角个人账户，去认证，比如通过支付宝扫码认证。（如果不认证，在后续调用大模型接口时可能会被403拒绝）

以上步骤完成后，我们就拥有了阿里通义千问大模型的免费的token了。

（4）配置环境变量

Windows通过cmd临时配置

拿到APIKEY后，打开cmd执行以下命令（等号后面不用加引号）：

Set OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

Set OPENAI_API_KEY=sk-dxxxxxxxxxx（示例 API KEY，需替换为个人实际 KEY）

Set MIDSCENE_MODEL_NAME=qwen-vl-max-latest #大模型名称

Set MIDSCENE_USE_QWEN_VL=1

注意：MIDSCENE_USE_QWEN_VL与MIDSCENE_USE_QWEN3_VL不能同时使用

Windows配置系统环境变量

按照指导文档，配置系统环境变量，可以保持永久生效。

四、Midscene.js 使用示例（YAML 文件方式）

1. 创建 YAML 文件

文件内容：打开百度搜索今日天气，断言显示搜索到的天气信息

复制代码

web:
url: https://www.baidu.com
tasks:
  - name: 搜索天气
flow:
      - ai: 搜索 "今日天气"
      - sleep: 3000
      - aiAssert: 结果显示天气信息

2. 运行 YAML 文件

（1）运行命令

打开 cmd，执行：midscene d:/test/test.yaml（路径需替换为实际 YAML 文件路径）

（2）运行过程示例

3、查看执行报告

用例执行后，在D盘midscene_run目录下面生成html的测试报告。

（1）报告基本信息

（2）执行步骤详情

|--------------------|--------|----|----------------------------------------------------------------------|
| 步骤 | 耗时 | 状态 | 说明 |
| Action - 搜索 "今日天气" | - | √ | 包含 Planning（6.48s）、Insight / Locate（0.13s）、Action / Input（0.99s）等子步骤 |
| 等待（sleep:3000） | 3s | - | 等待页面加载 |
| Assert - 结果显示天气信息 | 10.70s | √ | Insight / Assert 步骤，验证天气信息是否显示 |

（3）Token 使用情况

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| { "prompt_tokens": 1698, "completion_tokens": 73, "total_tokens": 1771, "time_cost": 6325, "model_name": "qwen-vl-max-latest", "model_description": "qwen-vl mode", "intent": "VQA" } |

（4）断言结果

Thought

：根据截图内容，页面显示了南京的天气信息，包括当前温度、风力、湿度、紫外线指数以及未来 15 天的天气预报，明确表明搜索结果展示了天气信息，因此陈述为真。
Assertion Result

：验证通过