Midscene.js：超详细部署与使用教程

Midscene.js 是字节跳动 Web Infra 团队开源的视觉驱动 GUI Agent 与端到端（E2E）测试框架：用自然语言描述「要做什么、期望看到什么」，由多模态视觉模型看屏幕、点按钮、做断言，把 UI 自动化从「维护一堆选择器」变成「写测试意图」。它支持 Web（Playwright / Puppeteer / Chrome 插件）、Android（ADB）、iOS（WebDriverAgent）、HarmonyOS（HDC）与桌面端（macOS/Windows/Linux，支持远程 RDP），一套 Agent API 跨平台复用。

目录

• 一、项目概述
• 二、环境要求
• 三、部署方式
• 四、使用方法
• 五、常见问题排查（FAQ）
• 六、部署注意事项与最佳实践
• 七、参考资料

一、项目概述

1.1 项目定位

传统 UI 自动化（Selenium/Playwright 脚本）的核心痛苦是「跟选择器搏斗」：按钮文案一变、DOM 结构一改，脚本就崩。Midscene.js 的思路是：让模型像人一样「看屏幕」——通过截图定位元素外观与位置，直接点、输、滚；再用自然语言断言「用户实际看到了什么」。它把 GUI Agent 能力做成两类用法：

1. Midscene Test（@midscene/test）：用 YAML 写测试用例，TypeScript 写可复用业务节点（Node），适合工程化 E2E 测试项目；
2. Agent SDK（@midscene/web 等）：把 aiAct / aiAssert / aiQuery / aiTap / aiInput 等 Agent API 嵌进你现有的 Playwright、Puppeteer 或独立脚本里。

官方口号：「像人一样看懂界面，用自然语言做 E2E 测试」。

1.2 核心功能

• 截图定位与操作：按外观和位置找元素，能点图标按钮、自定义控件、<canvas>、跨域 iframe，无需维护选择器、无需给元素加语义注解；
• 视觉断言：用自然语言描述期望界面（「选中方案有蓝色边框和对勾」「错误提示显示在邮箱输入框下方」），检查颜色、选中高亮、布局与视觉反馈；
• 一 API 跨平台：Web（Playwright/Puppeteer/桌面 Chrome Bridge）、Android（ADB）、iOS（WebDriverAgent）、HarmonyOS（HDC）、桌面端（macOS/Windows/Linux + RDP）；
• 多模型可选：支持 Qwen3.x、Doubao-Seed-2.1、DeepSeek V4 Flash、GLM-4.6V、gemini-3.5-flash、UI-TARS 等，含可自托管的开源模型；
• 交互式 HTML 报告：每次运行生成截图、元素定位、AI 决策过程、动作与断言结果的报告，可回放；
• Playground：Chrome 扩展里直接试指令、调提示词，不用先搭项目；
• Midscene Skills：让 AI 编程助手直接操作应用、验证界面。

官方 Benchmark（以 README 公布为准）：

1.3 技术架构

Midscene 的分层：

• 模型层：多模态视觉模型（截图 → 元素定位 + 动作决策），通过统一环境变量配置接入；
• Agent 核心：aiAct（自主流程）/ aiTap/aiInput（单步动作）/ aiAssert（断言）/ aiQuery（结构化数据提取）；
• 平台适配层：Playwright / Puppeteer / Chrome Bridge / ADB / WebDriverAgent / HDC / 桌面端原生键鼠；
• 工程化层：Midscene Test（YAML 用例 + TypeScript Node）、HTML 报告、Playground、CI 集成。

二、环境要求

三、部署方式

3.1 方式一：零代码体验（Chrome 扩展 Playground）

1. 打开 https://midscenejs.com/quick-start ，点 Chrome Web Store 按钮安装 Midscene 扩展；
2. 在 Chrome 扩展列表打开 Midscene，浏览器右侧出现侧边栏；
3. 点侧边栏设置图标，粘贴模型配置并保存：

# 以豆包 Seed 2.1 Turbo 为例（国内直连）
export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export MIDSCENE_MODEL_API_KEY="your-api-key"
export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
export MIDSCENE_MODEL_FAMILY="doubao-seed"

4. 打开任意图页（如 TodoMVC 示例），在侧边栏选 aiAct 输入指令运行。

用 Qwen、GLM、Gemini、GPT 等其他模型时，配置项写法见官方「模型选择指南 / 模型 API Key」文档；用 ChatGPT 订阅有单独接入流程。

3.2 方式二：嵌入现有 Playwright 工程（Agent SDK）

# 1) 安装依赖
npm install @midscene/web dotenv --save-dev
# 或 pnpm add @midscene/web dotenv --save-dev

playwright.config.ts 接入 Midscene 报告器：

import 'dotenv/config';
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  timeout: 90_000,
  use: { browserName: 'chromium' },
  reporter: [
    ['list'],
    ['@midscene/web/playwright-reporter'],
  ],
});

e2e/fixture.ts 注册 AI fixture：

import { test as base } from '@playwright/test';
import {
  PlaywrightAiFixture,
  type PlayWrightAiFixtureType,
} from '@midscene/web/playwright';

export const test = base.extend<PlayWrightAiFixtureType>(
  PlaywrightAiFixture(),
);

3.3 方式三：创建 Midscene Test 工程（YAML 用例）

按官方文档 https://midscenejs.com/midscene-test/use 创建测试工程，配置好模型与 Web runtime 后，直接写用例：

beforeEach:
  - gotoUrl: https://your-shop.example

cases:
  - name: Find headphones under $100
    steps:
      - aiAct: Search for headphones and filter the results to prices under $100
      - aiWaitFor: The filtered search results are visible
      - aiAssert: There are products in the search results, and each costs less than $100

3.4 配置模型环境变量

# Linux/macOS 写入 .env 或 shell 配置
# 这四项是最小集（以豆包 Seed 2.1 Turbo 为例）
export MIDSCENE_MODEL_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export MIDSCENE_MODEL_API_KEY="your-api-key"
export MIDSCENE_MODEL_NAME="doubao-seed-2-1-turbo-260628"
export MIDSCENE_MODEL_FAMILY="doubao-seed"

3.5 验证部署成功

# 1) 校验模型连通性
pnpm dlx @midscene/test@latest model verify

# 2) 跑一个最小用例
pnpm exec playwright test e2e/todo.spec.ts

# 3) 查看报告
ls midscene_run/report/   # 打开 HTML 报告，截图/定位/断言结果齐全即成功

四、使用方法

4.1 基础用法：Playwright 里写视觉测试

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

const agent = new PlaywrightAgent(page);

await agent.aiAct('Search for headphones and filter the results to prices under $100');
await agent.aiWaitFor('The filtered search results are visible');
await agent.aiAssert('There are products in the search results, and each costs less than $100');

对应 Playwright Test 写法（用 fixture）：

import { expect } from '@playwright/test';
import { test } from './fixture';

test('add a todo', async ({ page, aiAct, aiAssert }) => {
  await page.goto('https://todomvc.com/examples/react/dist/');
  await expect(page).toHaveTitle(/TodoMVC/);

  await aiAct('Add a todo named Try Midscene');
  await aiAssert('The todo list contains Try Midscene');
});

4.2 常用 Agent API

4.3 进阶功能

• 自定义 Node（Midscene Test）：把「准备订单数据 / 调 API / 清理」封装成 TypeScript Node，多个用例复用；还能导出 Node Spec 给开发者与 AI Agent 发现项目能力；
• 跨平台：同一套 Agent API 换到 Android（ADB）、iOS（WebDriverAgent）、HarmonyOS（HDC）、桌面端（RDP），文档见各平台章节；
• Puppeteer：除 Playwright 外支持 Puppeteer 接入；
• Chrome Bridge：桌面 Chrome 直接当 runtime，不依赖 Playwright；
• 缓存：可缓存 AI 规划与 DOM 定位结果，降低重复测试的模型调用成本；
• Gherkin BDD：支持用 Gherkin 语法写 BDD 脚本；
• Skills：给 AI 编程助手装 Midscene Skills，让它直接操作你本机应用验证界面。

4.4 适用场景

• Web 端 E2E 测试：替代脆弱的选择器脚本，面向「用户可见行为」写断言；
• 移动端自动化：Android/iOS/HarmonyOS 跨端 GUI 自动化；
• 桌面软件自动化：macOS/Windows/Linux 应用操作 + 远程 RDP；
• 冒烟测试与演示回放：CI 里定时跑关键链路，失败自动留截图报告；
• 原型验收：对设计稿还原度做视觉断言。

五、常见问题排查（FAQ）

Q1：扩展运行失败，提示 Cannot access a chrome-extension:// URL of different extension - 通常是其他 Chrome 扩展与 Midscene 冲突。到 chrome://extensions/ 逐个禁用排查，或临时开一个干净的 Chrome Profile 跑。

Q2：模型连不上 / 报错 - 检查四个 MIDSCENE_MODEL_* 环境变量是否正确加载（dotenv）；用 pnpm dlx @midscene/test@latest model verify 校验；确认模型支持视觉 UI 定位能力（纯文本模型不行）。

Q3：装不了 Chrome Web Store 扩展 - 可从 GitHub Releases 页下载安装包手动加载（chrome://extensions/ → 开发者模式 → 加载已解压扩展），缺点是没有自动更新。

Q4：aiAct 动作偏了 / 点错元素 - 把指令写得更具体（对象 + 动作 + 预期）；页面先等网络空闲（fixture 支持 waitForNetworkIdleTimeout）；必要时调 replanningCycleLimit 允许更多重规划次数。

Q5：报告在哪里看？ - 默认输出在 midscene_run/report/ ，打开 HTML 可看每步截图、元素定位、AI 决策过程与断言结果。

Q6：想在 CI（GitHub Actions）里跑 - 官方有「在 GitHub Actions 中运行」章节，按文档配置 runner 上的模型环境变量与 Chromium 即可。

Q7：成本高，一次测试烧很多 Token - 官方 AppControlBench 报告显示 Doubao Seed 2.1 Turbo 跑 60 个任务总成本约 0.59 美元；可开启 AI 规划/DOM 定位缓存，重复用例摊薄成本。

Q8：移动端测试怎么接？ - Android 走 ADB、iOS 走 WebDriverAgent、HarmonyOS 走 HDC，分别对应文档 platforms/android、platforms/ios、platforms/harmonyos。

Q9：Windows 下跑桌面端自动化 - 桌面端支持 Windows/macOS/Linux 原生键鼠控制与远程 RDP，按官方 platforms/desktop 文档配置。

Q10：想用 Python/Java 写 - 社区有 Python（Python51888/Midscene-Python）与 Java（Master-Frank/midscene-java、alstafeev/midscene-java）SDK，属社区维护，非官方。

六、部署注意事项与最佳实践

1. 先 verify 再接工程：模型连通性先 model verify 跑通，再写用例，避免在脚本里猜配置。
2. 指令要像「给人交代任务」：对象 + 动作 + 预期结果，越具体越稳；别写模糊的「处理一下」。
3. 模型选型看成本：截图式操作不发大段 DOM，模型成本可控；按官方各 Benchmark 报告选模型（追求成功率选 Gemini 系列，追求成本选豆包 Seed 2.1 Turbo）。
4. 断言面向「用户看到什么」：不要断言 DOM 结构，要断言视觉结果，这才抗 UI 改版。
5. 善用缓存：重复测试开启 AI 规划与 DOM 定位缓存，降本明显。
6. 报告即排查入口：失败先看 HTML 报告的失败步骤与模型返回原因，再改用例。
7. 版本配套：Playwright 版本与 Node 版本要满足兼容区间；升级 @midscene/web 前看 changelog。
8. MIT 协议：可商用，保留版权声明即可。
9. 敏感数据：截图会发给模型服务商，测试环境里别填真实敏感信息（密码、身份证）。
10. CI 隔离：CI runner 用无界面 Chromium + 独立模型 key，避免与开发环境混用额度。

七、参考资料

• GitHub 仓库：https://github.com/web-infra-dev/Midscene
• 官方文档：https://midscenejs.com
• 快速体验：https://midscenejs.com/quick-start
• Playwright 接入：https://midscenejs.com/integrate-with-playwright
• Puppeteer 接入：https://midscenejs.com/integrate-with-puppeteer
• Midscene Test 文档：https://midscenejs.com/midscene-test/overview
• 模型选择指南：https://midscenejs.com/model-selection
• 模型 API Key 配置：https://midscenejs.com/model-api-setup
• 示例项目：https://github.com/web-infra-dev/midscene-example
• AndroidWorld Benchmark：https://midscenejs.com/android-world-benchmark-report
• AppControlBench：https://midscenejs.com/app-control-bench-report
• Releases：https://github.com/web-infra-dev/Midscene/releases