Midscene.js框架（0）：零基础学习UI自动化测试

大多数 UI 自动化都依赖页面结构，包括读取 DOM 或无障碍树的 AI 工具。页面结构既脆弱又不完整：选择器一重构就失效；缺少语义化标注的元素，如纯图标按钮、自定义渲染的控件和 <canvas>，对它们是“看不见”的；原生应用和跨域 iframe 也难以触达；页面结构还无法判断界面实际看起来是否正确。

Midscene 走了一条不同的路：它仅凭截图、借助多模态模型工作，你只需像真人测试那样用自然语言描述每一步。

一、Midscene.js简介

Midscene 是一个用于视觉驱动 UI 测试与自动化的开源 SDK。你用自然语言描述每一步，Midscene 会驱动多模态模型为你规划并操作界面，核心优势有：

自然语言驱动，零编码门槛：用自然语言描述即可完成自动化操作
视觉感知，无惧 UI 变化：无需依赖 DOM 信息即可精确定位元素，基于多模态大模型，通过视觉理解页面内容
跨平台支持：支持web、Android、iOS、harmony、pc桌面
丰富的集成方式：Chrome 插件、JavaScript SDK集成到 Puppeteer 或 Playwright 项目中、YAML 脚本
可视化报告与调试：生成可视化报告，含动画回放和 AI 决策详情
支持缓存与多种模型：支持 GPT-4o、Qwen2.5-VL、UI-TARS、Gemini-2.5-Pro 等多种

二、Midscene.js自动化方式

1.自动规划

AI 自主规划并执行流程，完成任务。

await aiAct('逐一点击所有记录。如果某个记录包含文本"completed"，则跳过它');

2.工作流风格

将复杂逻辑拆分为多个步骤，以提高自动化代码的稳定性。

const recordList = await agent.aiQuery('string[], the record list')

for (const record of recordList) {

  const hasCompleted = await agent.aiBoolean(`check if the record ${record}" contains the text "completed"`)

  if (!hasCompleted) {

    await agent.aiTap(record)

  }}

三、模型选择与配置

1.官方推荐使用的多模态模型

模型系列	部署	Midscene 评价
豆包 Seed 模型快速配置	火山引擎版本： Doubao-Seed-2.1-turbo	⭐⭐⭐⭐⭐ 定位能力较强目前私有测评集中定位速度最快
千问 Qwen3.x 快速配置	阿里云 OpenRouter	⭐⭐⭐⭐ 综合效果优于 Qwen3-VL 和 Qwen2.5-VL
智谱 GLM-4.6V 快速配置	Z.AI (Global) BigModel (CN)	全新接入，欢迎体验模型权重开源HuggingFace
智谱 AutoGLM 快速配置	Z.AI (Global) BigModel (CN)	专用于移动端应用操作如需 aiAssert、aiQuery 等页面理解能力，建议搭配独立 Insight 模型
Gemini 3.x 系列快速配置	Google Cloud	⭐⭐⭐⭐⭐ gemini-3.5-flash 在私有测评集中定位表现最好价格高于豆包和千问

2.环境依赖与模型配置

2.1.web浏览器Chrome 插件（零代码）

2.1.1安装：从 Chrome 网上应用店安装 Midscene.js 插件。如果无法访问商店，可下载插件包后，在 Chrome 扩展程序页面开启“开发者模式”，选择“加载已解压的扩展程序”进行安装。

2.1.2配置：安装后，打开任意网页，点击浏览器右上角的插件图标打开 Midscene 面板。点击齿轮图标进入设置，将上文获取的模型环境变量粘贴进去即可。

在 Midscene Chrome 插件中，可以使用这种 export KEY="value" 配置格式

# 替换为你自己的 API Key

export MIDSCENE_MODEL_BASE_URL="https://.../compatible-mode/v1"

export MIDSCENE_MODEL_API_KEY="sk-abcde..."

export MIDSCENE_MODEL_NAME="qwen3.7-plus"

export MIDSCENE_MODEL_FAMILY="qwen3"

2.2.JavaScript SDK（编写脚本）

2.2.1系统要求

Node.js: 版本需 >= 18.19.0。部分 CLI 功能要求 Node.js 20.19+ 或更高版本。
包管理器: 推荐使用 pnpm 9.3.0+。

2.2.2安装步骤

安装依赖：在项目目录下，使用 npm 安装 @midscene/web 和 playwright。

npm install @midscene/web playwright tsx --save-dev

配置环境变量：在项目根目录创建 .env 文件，填入你的模型配置

（1）快速配置模型

如果你只想先跑起来，直接使用下面的配置即可，示例使用阿里云的 Qwen3.x：

export MIDSCENE_MODEL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"

export MIDSCENE_MODEL_API_KEY="your-api-key"

export MIDSCENE_MODEL_NAME="qwen3.7-plus"

export MIDSCENE_MODEL_FAMILY="qwen3"

（2）配置环境变量的方式

在项目的运行路径下创建一个 .env 文件，并添加以下内容，Midscene 的命令行工具默认会读取这个文件。

MIDSCENE_MODEL_BASE_URL="https://.../compatible-mode/v1"

MIDSCENE_MODEL_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

MIDSCENE_MODEL_NAME="qwen3.7-plus"

MIDSCENE_MODEL_FAMILY="qwen3"

2.2.3 引用 dotenv 库配置环境变量

dotenv 是一个零依赖的 npm 包，用于将 .env 文件加载到 Node.js 的环境变量 process.env 中。

# 安装 dotenv

npm install dotenv --save

在项目根目录下创建一个 .env 文件，并添加以下内容。注意这里不需要在每一行前添加 export。

MIDSCENE_MODEL_API_KEY="sk-abcdefghijklmnopqrstuvwxyz"

在脚本中导入 dotenv 模块，导入后它会自动读取 .env 文件中的环境变量。

import 'dotenv/config';

四、核心API介绍

配置完成后，你可以立即开始体验 Midscene。它提供了多个关键操作 Tab：

Act: 与网页进行交互，这就是自动规划（Auto Planning），对应于 aiAct 方法。比如

在搜索框中输入 Midscene，执行搜索，跳转到第一条结果；填写完整的注册表单，注意主要让所有字段通过校验。

Query: 从界面中提取 JSON 结构的数据，对应于 aiQuery 方法。

类似的方法还有 aiBoolean(), aiNumber(), aiString()，用于直接提取布尔值、数字和字符串。

提取页面中的用户 ID，返回 { id: string } 结构的 JSON 数据

Assert: 理解页面，进行断言，如果不满足则抛出错误，对应于 aiAssert 方法。

页面上存在一个登录按钮，它的下方有一个用户协议的链接

Tap: 在某个元素上点击，这就是即时操作（Instant Action），对应于 aiTap 方法。

点击登录按钮

五、快速开始实践项目

1.web浏览器插件

1.1 从 Chrome 应用商店安装 Midscene：

1.2 打开 Midscene 面板（可能被折叠在 Chrome 插件图标里）。浏览器右侧会出现一个侧边栏。

点击设置（齿轮）图标，粘你的模型配置。插件接受与上文配置模型相同的 export KEY="value" 格式。

点击保存后，打开任意网页，输入一条操作、数据提取或断言指令，点击run，即可看到 Midscene 为你操作页

midscene插件自动化运行中

运行完后，在视频的下方点击下载按钮即可下载测试报告

报告为html格式，在浏览器上可以进行打开，打开格式如下：

整体来讲，通过chrome插件的方式，完全不需要编写代码，只需要在浏览器中安装插件，配置支持的模型，并在midscene插件操作界面输入自然语言，AI即可进行理解、决策、执行等，最终输出报告。

2.通过编写脚本

2.1编写第一个脚本

import 'dotenv/config';
import { chromium } from 'playwright';
import { PlaywrightAgent } from '@midscene/web';

async function run() {
  const browser = await chromium.launch({
    headless: true,  // CI 环境用 true，本地调试可改 false
  });
  const context = await browser.newContext();
  const page = await context.newPage();

  try {
    const agent = new PlaywrightAgent(page);

    await page.goto('https://www.ebay.com');
    await agent.aiAct('在商品搜索输入框中输入"耳机"');
    await agent.aiAct('点击搜索按钮');
    await agent.aiAssert('搜索结果返回耳机商品列表')

    // 等待搜索结果加载
    await page.waitForTimeout(2000);

    // 可在这里加断言，验证搜索结果
    const title = await page.title();
    console.log('页面标题:', title);
  } catch (err) {
    console.error('执行失败:', err);
  } finally {
    await browser.close();
  }
}

run();

2.2运行脚本