Midscene.js｜AI自动化测试上手指南：一条指令跑通网页与真机操作

Midscene.js｜AI自动化测试上手指南：一条指令跑通网页与真机操作

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene

Midscene.js 是一个 GUI Agent 驱动的 E2E 测试框架，靠截图理解界面，再按自然语言指令完成点击、输入与断言，全程不写选择器。本文围绕 AI 自动化测试的三个里程碑展开：在浏览器里发出第一条指令、驱动一台 Android 真机、用本地脚本接管已登录的 Chrome。适合还没搭过环境、想先看到效果再写代码的测试工程师和开发同学，全程不需要克隆源码。

配齐模型并让浏览器听懂指令

目标：配上一个具备 UI 定位能力的多模态模型，打开网页输入一句话，页面自己动起来。

模型侧需要 4 个变量，以豆包为例：

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"

操作步骤：

1. 安装扩展：到 Chrome 应用商店加装 Midscene 插件，右侧随即出现侧边栏。
2. 粘贴配置：点侧边栏里的设置图标，把 4 个变量的值填进设置页并保存。
3. 下发指令：打开任意网页，在侧边栏输入「点击登录按钮」。

成功信号：侧边栏逐步回放每一步的 AI 决策与截图，执行结束后自动落盘一份带操作记录和断言结果的 HTML 报告。

该扩展与@midscene/webSDK 共享同一套核心实现，侧边栏里验证过的指令可以原样搬进脚本，写成agent.aiAct('点击登录按钮')。网页这条线通了，下一个目标是手机屏幕。

📱 连上 Android 真机并下发搜索指令

目标：让 AI 操作手机上的 App，每次点击、滚动都有截图留痕。

1. 打开调试：手机开发者选项里开启 USB 调试，再用数据线连接电脑。
2. 确认配对：执行adb devices -l，输出里出现设备序列号即配对成功。
3. 启动窗口：终端里运行下面这条命令，会弹出一个本地 Playground 窗口。

npx --yes @midscene/android-playground

4. 贴入密钥：点击窗口中的齿轮按钮，填入第 1 节的模型配置。
5. 下发指令：在输入框写「打开浏览器搜索 SU7」，提交后自动规划执行。

成功信号：执行结束后控制台输出Midscene - report file updated: .../xxx.html之类的路径，打开报告能逐步回看手机上的每次交互。

真机这条链路跑通后，同样的指令可以通过@midscene/androidSDK 写进正式测试脚本，集成细节见 Android 平台文档。手机这条线也通了，接下来处理登录态：本地 Chrome 里已登录的账号，脚本能不能直接用。

🔌 接管已登录的 Chrome 跑通脚本

目标：让本地脚本直接控制桌面版 Chrome，复用 cookies 与插件状态，免去重复登录。

1. 安装依赖：在项目目录执行npm install -D @midscene/web tsx。
2. 建立连接：脚本中创建桥接 Agent 并指向目标页面。

import { AgentOverChromeBridge } from '@midscene/web/bridge-mode'; const agent = new AgentOverChromeBridge(); await agent.connectNewTabWithUrl('https://www.bing.com'); await agent.ai('type "AI 101" and hit Enter');

3. 批准连接：运行脚本后扩展弹出确认窗，点 Allow 或 Always Allow。
4. 执行流程：aiAct、aiAssert等 API 照常调用，与浏览器内用法一致。

成功信号：桌面 Chrome 新开标签页并交脚本控制，脚本运行期间仍可在同一浏览器里手动补操作。

两个注意点：桥接模式下模型环境变量要配在终端侧，而不是浏览器侧；YAML 脚本里通过bridgeMode: newTabWithUrl接管本地 Chrome。机制细节可查 桥接模式文档。

📊 打开执行报告定位失败步骤

目标：执行结束后快速判断失败发生在哪一步、每一步花了多久。

1. 打开产物：运行产物默认落在midscene_run，其中报告、日志、缓存各占一个子目录。
2. 回放决策：打开 HTML 报告，逐步查看 AI 的输入、输出、元素定位框与单步耗时。
3. 迁移产物：设置MIDSCENE_RUN_DIR环境变量，可整体变更落盘目录。

成功信号：每个 AI 步骤的输入、输出、耗时、状态独立记录，慢在模型还是慢在页面，耗时数字能直接分辨。

报告由核心包统一产出，想深入生成机制可以看 报告生成模块。

对照故障现象并校准参数取值

现象 → 原因 → 处理

必填 / 选填参数

后续走两条路：主攻 Web 的话，按 模型配置参考 换用自己的模型服务商，在扩展里多发几条指令把措辞调顺；推进真机用例的话，处理设备授权问题后再执行一次 Playground，定位有没有偏差，报告里直接可见。

【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene