1. 从元素定位到自然语言为什么我盯上了 Midscene.js做 Web 自动化和 UI 测试的同学过去几年应该没少被元素定位折磨。xpath 写得又臭又长css selector 稍微改个 class 就凉了更别说现在前端框架天天迭代组件库一升级原来跑得好好的脚本直接大面积报错。我上一份工作里每天大概有三分之一的时间在维护老的自动化用例改完这个元素的定位另一个又崩了说实话挺崩溃的。后来看到豆包团队相关的开源项目 Midscene.js主打的就是通过自然语言驱动 Web 自动化等于直接把传统那套“找元素、做操作、写断言”的模式换掉了。你不需要再去纠结#main-content div.card:nth-child(2)这种字符串是从哪复制出来的只需要说一句人话比如“点击页面上的搜索框输入小米手机然后点搜索”Midscene.js 自己会去理解页面结构、定位目标、执行操作。这听起来确实像在做梦但实际是可行的。它的底层思路是让大模型去理解页面的视觉和 DOM 结构再转换成具体的操作指令而不是靠固定路径去锁定元素。测试脚本的健壮性、可维护性和编写速度都会有一次挺明显的提升。这篇主要是安装配置篇我先把环境搭建和初始配置讲清楚后面有机会再分享具体写用例的经验和踩坑记录。这篇文章适合谁看适合已经被传统 UI 自动化维护成本折磨过的测试开发工程师适合想用 AI 能力批量生成 Web 操作脚本的前端同学也适合产品、运营这类非技术岗位想自己跑通浏览器自动化流程的人群。2. 环境准备别急着装先把机器搞干净2.1 Node.js 和 Python 的版本要求Midscene.js 是一个基于 JavaScript 生态的工具所以 Node.js 是必须的。我建议装 Node.js 18 以上版本最好直接用最新 LTS实测在 Node 16 上跑会有兼容提示虽然能勉强运行但连接浏览器的过程中偶发超时没必要踩这个坑。安装完之后在终端里验证一下node -v npm -v只要这两条命令能正常输出版本号Node 环境就算过了。如果你机器上已经装了 nvm 或 fnm 这类版本管理工具记得切换到一个干净的 Node 版本再继续避免和老项目依赖打架。Python 这边需要装 3.9 以上版本但严格来说它并不是运行 Midscene.js 的硬性要求。你可能会问那为什么还要提 Python因为我后续计划配合一些 AI 辅助脚本做批量回归场景而且部分浏览器控制工具在 Python 环境里有一种更顺手的调用方式提前把 Python 环境准备好后面扩展功能的时候不用再来回切环境。装好后同样验证一下python3 --version2.2 浏览器选择Chrome 还是 ChromiumMidscene.js 的核心能力是通过浏览器调试协议去驱动浏览器动作所以你需要一个能稳定对接的浏览器。Chrome 和基于 Chromium 内核的 Edge 是最稳妥的选择因为它们对调试协议的支持比较完善。实际测试中我用的是 Chrome因为它的远程调试接口最稳定出现问题的时候排查资料也最多。在 Windows 上需要留意浏览器自动更新的位置在 macOS 上则要注意允许终端应用进行控制这两个是新手最容易卡住的环节。2.3 豆包 API Key没有它模型不会干活Midscene.js 虽然本身是开源工具但自然语言转操作指令这件事背后需要大模型来支撑。豆包是目前我测试下来速度、中文理解能力都挺均衡的一个选择关键是它和 Midscene.js 的适配也足够顺畅。去豆包的开发者平台注册账号创建一个应用之后就能拿到 API Key。注意这个 Key 是敏感信息不要随便提交到 Git 仓库或者分享给别人一旦泄露立刻去平台侧轮换掉。拿到 Key 之后把它配置到环境变量里这样在使用 Midscene.js 的时候连接器会自动读取。先提前说一句Midscene.js 支持的模型不止豆包一个但在我写这篇安装配置篇的时候主流方案是走豆包的接口。如果你用的是其他兼容接口只要在配置上把地址和模型名对齐也是一条可行的路线。3. Midscene.js 安装从零到跑通的最短路径3.1 用 npm 安装核心依赖安装过程本身不复杂但“不复杂”和“不踩坑”是两码事。我建议在一个全新的目录里操作不要把公司老项目和其他工具混在一起。mkdir midscene-demo cd midscene-demo npm init -y npm install midscene第一条npm init -y会生成一个默认的 package.json后面安装的依赖都会集中管理在这里。npm install midscene会把 Midscene.js 主包拉下来这是整个工具的核心。如果你对 Playwright 或 Puppeteer 已经比较熟悉会发现 Midscene.js 的设计思路和它们很像但也有关键区别它底层确实整合了浏览器控制能力但你在写用例的时候不需要直接面对那些细粒度的浏览器 API自然语言描述直接就能变成动作序列。安装完之后检查一下npm list midscene能列出 midscene 的版本号就说明装上了。如果这里出现 EACCES 权限错误通常是 npm 全局目录权限的问题用 nvm 重装 Node 往往能一并解决。3.2 安装浏览器调试辅助件Midscene.js 主包安装好之后还需要让浏览器能够被它正确识别和驱动。这里有两种选择一种是使用 Playwright 的浏览器管理能力另一种是直连已经打开的 Chrome。npm install playwright npx playwright install chromium第一条命令装的是 Playwright 这个自动化库第二条命令会下载一个独立的 Chromium 内核。这个内核的好处是跟系统里你自己装的 Chrome 完全隔离版本由 Playwright 自己管理测试环境干净、可重现不会被日常使用的浏览器配置干扰。如果你不想额外下载一个浏览器内核也可以走“直连自己常用浏览器”的方案这在后面的配置文件里会体现。两种方案的区别我会在配置那一节详细讲。3.3 环境变量配置不要硬编码密钥很多新手图省事直接把 API Key 写在代码里然后代码一提交到仓库Key 就全公司可见了。这种事我见过不止一次关键是出事了不仅丢人还得花时间处理密钥轮换和后续的权限排查。正确做法是配置环境变量。在 macOS 或 Linux 下export MIDSCENE_API_KEY你的豆包API Key export MIDSCENE_MODEL_NAMEdoubao在 Windows PowerShell 下$env:MIDSCENE_API_KEY你的豆包API Key $env:MIDSCENE_MODEL_NAMEdoubao每次打开终端都要重新 setenv挺麻烦的。我建议顺便在项目根目录下建一个.env文件把变量写进去然后在启动脚本里加载。Node.js 项目里可以用dotenv这个库来读取npm install dotenv加载方式是在你的入口文件最顶部加一行require(dotenv).config()这样环境变量会从.env文件里自动读进来。注意.env文件本身一定要加进.gitignore切记。4. 配置浏览器连接方式两种方案按需选择4.1 方案一Playwright 托管浏览器这种方式适合大多数人尤其是你追求开箱即用的体验。Midscene.js 会通过 Playwright 启动一个受控的 Chromium 进程脚本跑完浏览器自动关闭不污染你日常浏览会话。优点是环境隔离干净缺点是如果你需要调试页面视觉效果不方便进行交互式检查。示例代码如下import { Agent } from midscene import { PlaywrightConnect } from midscene const agent new Agent({ connect: new PlaywrightConnect({ browserType: chromium, }), mode: natural-language, })这里browserType支持chromium、firefox、webkit但我建议你老老实实用 chromium因为 WebKit 的兼容性几轮版本下来都还有小毛病而 Firefox 在自然语言指令转换为视觉效果时的截图解析偶尔会有延迟。Chromium 在性能、解析准确率和稳定性上目前是最平衡的。4.2 方案二直连本机已打开的 Chrome这种方案更适合你在开发阶段希望边看边改或者你需要在已经登录态的浏览器里面执行操作。比如你要测试一个已经登录后台的页面如果每次都由 Playwright 启动一个全新浏览器登录态就没了你还得额外写一套登录逻辑非常烦。直连已经打开的 Chrome需要你先以调试模式启动浏览器。在启动 Chrome 之前先关掉所有 Chrome 进程然后执行# macOS /Applications/Google Chrome.app/Contents/MacOS/Google Chrome --remote-debugging-port9222 # Windows C:\Program Files\Google\Chrome\Application\chrome.exe --remote-debugging-port9222然后 Midscene.js 通过这个调试端口去接管浏览器的行为。示例代码import { Agent } from midscene import { BrowserConnect } from midscene const agent new Agent({ connect: new BrowserConnect({ port: 9222, }), mode: natural-language, })走这种方式时你可以在浏览器里面自由操作甚至开多个标签页Midscene.js 只对当前激活的标签页执行指令。4.3 两种方式的选型建议我结合自己的实际使用经验说一下选型依据跑回归测试和平时写独立用例建议优先用 Playwright 托管方式但如果你是在做日常页面测试、需要人工多看几眼交互细节或者遇到需要登录态的页面建议直连本机 Chrome。这两种方式之间切换非常方便只需改一下 connect 的配置就行。场景推荐方式原因回归测试Playwright 托管环境干净无人工干扰调试交互逻辑直连 Chrome实时可见方便发现问题需要登录态直连 Chrome省去维护登录态的逻辑批量数据验证Playwright 托管支持并发、可重复执行5. 跑通第一条自然语言用例5.1 最小的自动化脚本环境都配好之后我们来写一个最小的自动化脚本。这个脚本的作用是打开一个网页用自然语言执行一个搜索操作然后输出页面标题。我拿公开的某搜索引擎页面举例你换成别的页面也没问题。const { Agent } require(midscene) const { PlaywrightConnect } require(midscene) require(dotenv).config() async function main() { const agent new Agent({ connect: new PlaywrightConnect({ browserType: chromium, headless: false, }), mode: natural-language, }) await agent.goto(https://www.baidu.com) await agent.ai(在输入框中输入 自动化测试 并点击搜索按钮) const title await agent.getCurrentPageInfo() console.log(title.title) } main()这里headless: false表示浏览器以有头模式运行你能看到它实际操作的过程。如果你希望跑批处理、不弹窗可以把headless改成true。到这一步你会发现全程代码量非常少没有任何document.querySelector或者page.click(#search)这类操作你只需要把“我要做什么”告诉它就行。5.2 理解“自然语言指令”的执行链路上述agent.ai是一个很神奇但也可能很抽象的方法。你可能会好奇它到底是怎么理解一句话并去页面上找元素的简单说它会把当前页面的截图和 DOM 结构发到豆包模型模型返回一个结构化操作序列比如[{action: input, content: 自动化测试, target: 搜索框}, {action: click, target: 搜索按钮}]然后 Midscene.js 再把这些结构化操作翻译成真实的浏览器动作。换句话说自然语言只是你对外沟通的接口真正的执行链路还是“视觉理解 结构化动作”。理解这一点很重要因为这意味着你给出的指令越贴近页面的视觉特征模型定位就越准确。你自己心里要有一个映射逻辑指令里的文本要能在页面上直接找到对应内容。5.3 执行结果和断言脚本跑完之后除了看浏览器里有没有正常操作之外更重要的是对结果做断言。在传统测试框架中你要写很长一串expect(selector).toHaveText(...)而 Midscene.js 允许你直接用自然语言去断言const result await agent.aiEvaluate(页面上是否出现了 搜索结果 相关的文字如果有请总结第一条搜索结果的标题) console.log(result)这段代码会交给模型去判断页面内容并返回你想要的信息。它等于把“读取页面数据”和“判断结果是否符合预期”这两步合并到了一步。我跑下来整体体验是这条链路在一般的中文网页上表现很稳模型对中文文字的理解度明显比传统正则、关键字匹配聪明太多。6. 常见问题与排查技巧实录6.1 安装时报错和依赖冲突安装阶段遇到最多的问题是权限报错或者版本冲突。如果你用了公司的私有 npm 源注意私有源上 midscene 版本可能更新不及时导致拉到的是旧版本从而出现Agent这个类未导出的报错。解决办法有两个方向一是临时切换到 npm 官方源重新安装二是检查 package.json 里 midscene 版本号是否为最新版本。npm install midscenelatest还有一个典型问题是和 Puppeteer 或 Playwright 高版本一起装时会出现browserType冲突。这种情况大多是因为不同包对/usr/bin/chromium或 Chrome 路径的寻找顺序不一样。最简单的排查方式就是全部重装依赖rm -rf node_modules package-lock.json npm install注意package-lock.json如果删掉再安装版本会重新解析有可能会带来新的变化但通常也是解决依赖混乱最彻底的手段。6.2 API Key 相关认证失败或额度不足如果你遇到认证失败优先检查环境变量是否真的被读取到了。可以在代码里打印一下process.env.MIDSCENE_API_KEY看是否有值。如果.env文件在.gitignore之外或者没有通过 dotenv 加载环境变量确实读不到。额度不足的问题我在实际测试中也遇到过。豆包接口默认有一些免费的调用配额一旦用完就会返回 429 或者类似提示。这种情况下没有别的花招去开发者平台看一下配额情况等次日重置或者充值。值得提醒的是自然语言驱动 UI 自动化这种方式消耗的 token 比传统脚本要高不少因为它需要把页面截图和 DOM 结构都发给模型。如果你在跑大型回归用例集务必评估一下 API 调用量的成本不然月底账单出来会有点疼。6.3 浏览器连接失败和超时直连 Chrome 最常见的坑是忘记关掉已经运行中的 Chrome 进程直接执行带调试端口的启动命令。你会发现新开的命令没有效果页面也连不上。正确的做法是先把所有 Chrome 窗口全部关闭再执行带--remote-debugging-port9222的启动命令。如果仍然失败检查端口是否被占用lsof -i :9222有这条输出才说明调试端口真的起来了。没有输出就说明 Chrome 没把调试接口打开大概率是启动命令没生效。Playwright 托管模式下遇到启动超时可以去检查 Chromium 内核是否已经成功下载。在国内网络环境下npx playwright install chromium有可能下载失败这种情况可以换个镜像源再试但要注意合规问题尽量走正规渠道。6.4 自然语言指令执行结果不稳定最后这个问题可能是自然语言驱动方式最需要心理准备的一点模型的理解偶尔会有偏差同样一句话这次跑和下次跑理论上有微小概率选出不同的元素。我在实操中总结了一些提高稳定性的经验。一是指令描述要尽量具体避免歧义。比如“点一下那个蓝色的按钮”就不如“点击页面右上角的‘立即购买’按钮”稳定。二是如果页面上有多个相似元素在指令里加入位置描述比如“左侧列表中的第二个选项”。三是关键流程执行完后建议通过aiEvaluate做一次结果确认确保动作真的生效。另外Midscene.js 有一个录制插件也就是 Recorder可以帮助你通过浏览器交互记录操作过程再导出自然语言脚本。这个工具对快速生成用例非常有帮助我建议你在安装配置完成后就去体验一下。录制过程中你的点击、输入、跳转都会被记录下来生成的脚本再手工微调一下效率会很高。7. 关于豆包与 Midscene.js 搭配的几点心得7.1 为什么选择豆包这个模型Midscene.js 在设计上可以接入多种大模型不强制绑定某个服务商。但我测试下来豆包的接口稳定性和响应速度给我留下的印象最深。特别是中文长句的理解能力在常见网页场景下几乎没有歧义理解错误。配置上也比较简单模型名直接写doubao即可不需要去查一堆别名。你可以根据自己的使用场景去尝试其他模型但我建议在入门阶段先用豆包把整个链路跑通之后再逐步去对比不同模型在实际用例上的表现差异这样不容易被多个变量的干扰带偏。7.2 自然语言 UI 自动化的适用边界我必须诚实指出自然语言驱动 UI 自动化并不是银弹。它特别适合页面结构频繁变化、逻辑复杂但文案稳定的业务系统比如后台管理系统、运营平台、数据报表系统等。但如果是那种大量动态渲染、无稳定文字标签、纯粹靠图形视觉交互的页面模型的理解成本就会升高不如传统方式可控。这也是我为什么在标题里说“全新体验”而不是“全面替代”——它带来的是编写和维护体验上的跃升但在断言严谨性和执行可重复性上仍然需要你设计合理的校验策略来把关。8. 最后分享一个配置小技巧配置完整个环境之后我建议你把这些依赖和配置整理成一个模板项目推到一个固定的代码仓库。这样下次在新电脑或者新同事那搭环境几行命令就能复制出一套可用环境来不用重新踩一遍配置坑。我自己的模板项目结构大致如下midscene-demo/ ├── .env # 环境变量包含API Key不进Git ├── .gitignore # 忽略 .env、node_modules 等 ├── scripts/ │ ├── run_demo.js # 最小的自然语言用例 │ ├── run_recorder.js # 启动 recorder 的入口 ├── tests/ │ ├── login.test.js │ └── search.test.js ├── package.json └── README.md借助 Recorder 录制功能配合自然语言维护脚本整体效率比传统方式高一截。如果你准备在团队里推广这套方案我建议先从两三个高频回归用例开始试点让团队看到效果之后再逐步扩大覆盖范围。我的实际体验就到这里为止接下来你可以先去把环境装了跑通第一个自然语言用例然后再回来读我后续要分享的实战篇和最佳实践篇。