企业官网建设流程全解析

Midscene.js：把一句自然语言变成跨平台 UI 自动化测试的强力工具

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

想验证「在网页上搜索耳机、确认结果非空」这类流程，用 Midscene.js 不需要写一个选择器。它是一款视觉 AI 驱动的 GUI 自动化测试框架（GUI Agent for E2E Testing）：只靠截图理解界面，用多模态模型定位元素，再由它完成点击和输入。

同一套 API 可以接入 Web、Android、iOS、HarmonyOS 和桌面端（Windows / macOS / Linux）。只要目标界面能被截图，它就能被自动化。

它到底能做什么：视觉自动化的 4 个核心能力 🎯

1. 用自然语言操作与断言aiAct接收多步目标，自主规划、执行并中途验证；aiAssert用一句话校验「用户真正看到的东西」，而不只是判断节点是否存在；aiQuery可以直接从画面里提取结构化数据，比如商品列表的{name, price}[]。针对单步操作还有aiTap、aiInput等即时接口，更快也更省 token。

2. 不依赖页面结构纯图标按钮、<canvas>、原生应用、跨域 iframe，选择器路线的工具很难触达，而 Midscene.js 只按截图定位——人眼能看到的，它就能找到。UI 重构后也不用追着改选择器。

3. 跨平台统一 API同一个agent.aiAct('...')，在 Playwright、Puppeteer 浏览器环境里能用，在 Android、iOS、HarmonyOS 真机和桌面端也能用，测试逻辑可以跨平台复用。

4. 报告与缓存提速每次运行自动产出 HTML 报告，包含每一步的截图、动作与耗时。启用缓存后，已验证过的规划与元素定位会被复用，官方示例中同一脚本的重复执行耗时从 51 秒降到 28 秒。

三步跑通第一次体验 🚀

第一步：配置视觉模型。Midscene.js 需要外接一个具备 UI 定位能力的多模态模型，设置 4 个环境变量即可（以 Doubao Seed 为例，Qwen、GLM、UI-TARS 等同样支持，各模型写法见 模型配置）：

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"

第二步：安装依赖。在项目里执行npm install @midscene/web playwright tsx --save-dev。

第三步：写一个最小脚本并运行。保存为demo.ts：

// demo.ts：打开 Bing 搜索并断言结果 import { chromium } from 'playwright'; import { PlaywrightAgent } from '@midscene/web/playwright'; import 'dotenv/config'; // 从 .env 读取上面的模型配置 const browser = await chromium.launch({ headless: false }); const page = await browser.newPage(); await page.goto('https://www.bing.com'); const agent = new PlaywrightAgent(page); await agent.aiAct('搜索"天气"并按回车'); // 自然语言操作 await agent.aiAssert('页面展示了天气信息'); // 自然语言断言

运行npx tsx demo.ts，浏览器会自动打开、完成搜索并自检。结束后终端会打印报告文件路径，用浏览器打开即可回看每一步的截图与执行过程。

典型使用场景 🧭

浏览器 E2E 回归测试—— 解决的问题：选择器频繁失效、无法验证「界面看起来是否正确」。适合前端与测试团队：把 Midscene.js 装进现有 Playwright 项目，保留熟悉的用例结构，补上视觉层面的断言。

移动端真机测试—— 解决的问题：控制真机通常还要额外搭设备驱动层。Midscene.js 直接按截图操作 Android、iOS 真机，一句aiAct就能打开设置、核对版本号，适合移动应用的功能测试与回归。

复用已登录浏览器（桥接模式）—— 解决的问题：有些流程必须带着已有账号的 cookie 和登录态。桥接模式让本地脚本直接接管你正在使用的桌面 Chrome，人和脚本可以交替操作同一窗口，适合场景验证与需要登录态的流程。

实用避坑建议 ⚠️

• 你会遇到：元素定位不准。可以开启deepLocate做多轮深度定位，或给aiAct加deepThink加强任务拆解；若是模型本身不擅长 UI 定位，直接换一个更擅长的。

• 你会遇到：重复执行又慢又贵。给 Agent 配置cache后，规划与定位结果会落盘复用；注意aiQuery、aiAssert这类查询操作不缓存，每次仍会调用模型。
• 你会遇到：单步操作花费偏高。aiAct是自主规划，时间和 token 消耗都更高；路径确定的单步动作，改用aiTap、aiInput这类即时接口。
• 你会遇到：报告文件过大。默认单 HTML 会把截图以 base64 内嵌，可改为外部资源格式，再用本地 HTTP 服务器（如npx serve）访问报告目录。

Midscene.js 的核心，是把「写选择器」换成「写一句话」，并用一套 API 覆盖 Web、移动端和桌面端。更多进阶用法（YAML 脚本、Test Runner）可从 快速开始指南 入手，社区交流与更新信息见 README.zh.md。

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