Midscene + Playwright：视觉驱动 Web UI 自动化落地指南

1. 为什么视觉驱动是 Web UI 自动化的一条新路

做过 Web UI 自动化的人都有一个共同的痛：页面一改，脚本就红。传统方案靠 DOM 选择器定位元素，id、class、xpath写了一大堆，前端换个构建工具、加个哈希后缀，整条用例链就崩了。维护成本高到很多团队干脆放弃 UI 层，只做接口测试。但业务方不认这个账，他们要看的是"用户点进去能不能下单"，接口全绿不代表页面没白屏。

Midscene 这个工具进入视野，是因为它换了个思路：不跟 DOM 死磕，而是让多模态大模型"看"页面截图，用自然语言描述操作意图，由模型输出可执行的浏览器动作。你写的是"点击登录按钮"，而不是page.click('#login-btn > span')。这背后的技术组合是 Playwright 负责浏览器控制与截图，视觉语言模型负责理解页面结构和定位目标，两者通过一层桥接协议串起来。

这套方案解决的核心问题是脚本脆弱性和编写门槛。产品经理描述一个流程，理论上可以直接转成可执行脚本，不需要测试工程师逐行翻译成选择器。当然它也不是银弹，模型调用有延迟、有成本，复杂交互的稳定性还需要工程手段兜底。这篇文章就把 Midscene 在 Web UI 自动化里的落地路径拆开讲清楚，包括它和 Playwright 怎么配合、视觉驱动脚本怎么写、实际跑起来会遇到哪些坑。适合已经用过 Playwright 或 Selenium、想了解 AI 自动化测试新范式的同学，也适合刚接触自动化测试、想直接上手新工具的新人。

2. Midscene 与 Playwright 的协作机制拆解

2.1 视觉驱动到底"驱动"了什么

先把概念理清楚。视觉驱动不是说完全不用 DOM，而是把"定位元素"这件事从人工写选择器，转交给模型基于截图做判断。整个链路大致是这样：

1. Playwright 打开页面，等待网络空闲，截取当前视口或全页截图。
2. 截图连同当前的操作指令（比如"在搜索框输入关键词"）一起发给视觉语言模型。
3. 模型返回一个结构化的动作描述，包含目标元素的坐标或语义标识，以及动作类型。
4. Midscene 把这层描述翻译成 Playwright 的原生 API 调用，比如page.mouse.click(x, y)或locator.fill()。
5. 执行后再截图，进入下一轮，形成"感知—决策—执行"的闭环。

这里有个关键设计：Midscene 并不是每一步都纯靠坐标点击。它会在模型返回结果后，尝试用 Playwright 的语义定位能力去匹配，比如模型说"点击文本为'提交'的按钮"，Midscene 会优先用getByRole('button', { name: '提交' })去定位，定位不到才退化为坐标点击。这个优先级策略很重要，因为坐标点击对页面滚动、分辨率变化极其敏感，而语义定位更稳。

2.2 为什么选 Playwright 而不是 Selenium

热词里同时出现了 Playwright 和 Appium，说明大家在选型时确实纠结。Midscene 官方桥接的是 Playwright，原因有几个层面。

第一是自动等待机制。Playwright 的actionability检查是内置的，点击前会自动等待元素可见、稳定、可接收事件。Selenium 需要自己写WebDriverWait，稍不注意就ElementClickInterceptedException。视觉驱动场景下，模型返回动作后如果元素还没渲染完，Playwright 能兜住，Selenium 就得额外加睡眠。

第二是截图能力。Playwright 支持元素级截图、全页截图、带遮罩截图，还能在截图时禁用动画，这对视觉模型的输入质量影响很大。Selenium 的截图 API 相对粗糙，全页截图在长页面上经常出问题。

第三是多浏览器一致性。Playwright 自带 Chromium、Firefox、WebKit 三套内核，API 统一。视觉驱动脚本换浏览器时，只要模型能正确识别页面，底层切换成本几乎为零。

第四是网络拦截与 Mock。做 UI 自动化时经常要 mock 后端返回，Playwright 的page.route()用起来比 Selenium 的代理方案顺手太多。视觉驱动脚本里，前置数据准备往往靠路由拦截完成，这一点 Playwright 优势明显。

2.3 模型调用的两种模式：在线与本地

Midscene 支持接入不同的视觉模型。在线模式调用云端多模态 API，优点是识别能力强、无需本地算力；缺点是每次操作都有网络往返，延迟通常在 1 到 3 秒，且按 token 计费，跑大批量用例时成本要算清楚。

本地模式可以接一些开源的多模态模型，延迟低、数据不出内网，但对页面复杂度的容忍度会下降，尤其是中文界面、密集表格、自定义控件的识别准确率，和云端大模型有明显差距。

我的建议是：开发调试阶段用在线模型快速验证流程，回归测试阶段把高频稳定路径固化成传统选择器脚本，只把易变部分留给视觉驱动。全量视觉驱动听起来很美，实际跑起来时间和费用都吃不消。

3. 环境搭建与第一个视觉驱动脚本

3.1 依赖安装与常见报错处理

热词里"npx playwright install 失败"和"未安装 playwright"出现频率很高，说明环境问题是新手第一道坎。标准流程如下：

# 初始化项目 npm init -y # 安装 Playwright 与 Midscene npm install -D playwright @midscene/web # 安装浏览器内核 npx playwright install chromium

如果npx playwright install卡住或失败，通常是网络问题。可以设置镜像源：

# Linux / macOS export PLAYWRIGHT_DOWNLOAD_HOST=https://npmmirror.com/mirrors/playwright # Windows PowerShell $env:PLAYWRIGHT_DOWNLOAD_HOST="https://npmmirror.com/mirrors/playwright" npx playwright install chromium

另一个常见问题是系统缺少浏览器依赖库，Linux 上执行：

npx playwright install-deps chromium

注意：不要用sudo npm install装 Playwright，权限混乱会导致后续npx playwright install找不到正确的缓存目录。项目级安装永远优于全局安装。

3.2 配置模型接入参数

Midscene 需要一个模型配置，通常通过环境变量或配置文件注入。以在线模型为例，配置结构大致如下：

// midscene.config.js module.exports = { model: { provider: 'openai-compatible', baseURL: process.env.MODEL_BASE_URL, apiKey: process.env.MODEL_API_KEY, modelName: process.env.MODEL_NAME, temperature: 0 }, screenshot: { fullPage: false, disableAnimations: true } };

temperature设为 0 是为了让模型输出稳定，同样的页面截图尽量返回同样的动作描述。disableAnimations必须开，否则截图时元素还在过渡动画中，模型看到的和实际可点击的位置对不上。

3.3 第一个脚本：搜索并断言结果

下面是一个最小可运行示例，用 TypeScript 写，因为 Midscene 的类型提示对开发体验帮助很大。

import { chromium } from 'playwright'; import { MidsceneAgent } from '@midscene/web'; async function main() { const browser = await chromium.launch({ headless: false }); const page = await browser.newPage(); await page.goto('https://example.com'); const agent = new MidsceneAgent(page, { modelConfig: require('./midscene.config') }); // 视觉驱动操作 await agent.aiAction('在搜索框中输入 "自动化测试"'); await agent.aiAction('点击搜索按钮'); await agent.aiWaitFor('搜索结果列表已经加载完成'); // 视觉断言 const result = await agent.aiAssert('页面中应该包含至少一条搜索结果'); console.log('断言结果:', result); await browser.close(); } main();

这段代码里，aiAction负责操作，aiWaitFor负责等待条件，aiAssert负责断言。三个 API 覆盖了 UI 自动化的核心动作。注意aiWaitFor不是简单睡眠，它会循环截图判断条件是否满足，直到超时。

4. 视觉驱动脚本的编写策略与稳定性优化

4.1 指令怎么写模型才听得懂

视觉驱动的脚本质量，八成取决于指令措辞。写得太模糊，模型定位不到；写得太具体，又失去了视觉驱动的灵活性。我的经验是遵循"区域 + 目标 + 动作"三段式。

比如"点击登录按钮"就不如"在页面右上角区域，点击文本为'登录'的按钮"。前者模型可能找到页面中间某个也叫登录的链接，后者限定了空间范围，准确率明显提升。

再比如输入操作，要明确输入框的特征："在标有'手机号'的输入框中输入 138xxxx"。如果页面上有多个输入框，不指明特征模型就会猜。

实操心得：把常用指令沉淀成模板，比如在[区域]中[动作][目标]，团队共用一套措辞规范，能显著降低模型理解偏差。

4.2 截图策略对识别率的影响

默认全页截图在长列表页面上会让模型"看花眼"，目标元素被压缩得太小。更好的做法是视口截图 + 滚动定位。Midscene 支持配置截图范围，对于需要操作页面下方元素的情况，先用aiAction('滚动到页面底部')或 Playwright 原生page.mouse.wheel()把目标区域带入视口，再执行视觉操作。

另一个技巧是局部截图。如果已知操作区域在某个容器内，可以先用 Playwright 定位容器，对该容器截图后交给模型，输入信息量小，识别更快更准。

const searchPanel = page.locator('.search-panel'); const box = await searchPanel.boundingBox(); await agent.aiAction('在搜索面板中输入关键词', { screenshotClip: box });

4.3 混合定位：视觉兜底 + 语义优先

纯视觉驱动在稳定页面上是浪费。我的做法是能语义定位就语义定位，语义定位失败再走视觉。Midscene 本身有这个优先级，但脚本层面也可以显式控制。

// 优先尝试语义定位 const loginBtn = page.getByRole('button', { name: '登录' }); if (await loginBtn.count() > 0) { await loginBtn.click(); } else { // 兜底走视觉 await agent.aiAction('点击页面中的登录按钮'); }

这种混合模式在回归测试里特别实用：主流程用稳定选择器，UI 改版导致选择器失效时，视觉驱动自动接管，用例不会直接挂掉，而是给出"选择器失效但视觉定位成功"的告警，提醒你更新选择器。

4.4 等待与重试机制的设计

视觉模型有概率返回错误动作，网络也有概率抖动。脚本必须内置重试。Midscene 的aiAction支持重试配置，但更稳妥的是在业务层包一层。

async function robustAction(agent, instruction, maxRetry = 3) { for (let i = 0; i < maxRetry; i++) { try { await agent.aiAction(instruction); return; } catch (e) { console.warn(`第 ${i + 1} 次尝试失败: ${e.message}`); await agent.page.waitForTimeout(1000); } } throw new Error(`操作失败: ${instruction}`); }

重试之间加一点等待，让页面状态稳定下来。但重试次数不要超过 3 次，否则一个用例卡住会拖垮整个测试套件。

5. 与 pytest 及 CI 流程的集成

5.1 用 pytest 组织视觉驱动用例

热词里 pytest 出现多次，Python 技术栈的团队很多。Midscene 有 Python 版本，可以配合 pytest 写用例。

import pytest from midscene import Agent from playwright.sync_api import sync_playwright @pytest.fixture(scope="session") def browser(): with sync_playwright() as p: browser = p.chromium.launch() yield browser browser.close() @pytest.fixture def page(browser): page = browser.new_page() yield page page.close() def test_search_flow(page): page.goto("https://example.com") agent = Agent(page) agent.ai_action("在搜索框中输入 '自动化测试'") agent.ai_action("点击搜索按钮") assert agent.ai_assert("搜索结果列表非空")

pytest 的 fixture 机制天然适合管理浏览器生命周期，scope="session"让整个测试会话共用一个浏览器实例，省去反复启动的开销。

5.2 测试报告与失败截图

视觉驱动用例失败时，光看报错信息没用，必须看截图。Midscene 在每次操作时会缓存截图，可以在conftest.py里挂 hook，失败时把截图和模型返回的原始动作描述一起存下来。

@pytest.hookimpl(tryfirst=True, hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: page = item.funcargs.get("page") if page: page.screenshot(path=f"reports/{item.name}_failure.png")

这份截图加上模型当时的判断依据，是排查问题的黄金组合。很多时候你会发现不是脚本写错了，而是页面加载慢导致模型看到了骨架屏。

5.3 CI 环境下的注意事项

CI 机器通常是无头模式，headless: true。视觉驱动在无头模式下要注意两点：一是字体渲染，Linux 容器里中文字体缺失会导致截图里中文变方块，模型直接识别不了。安装fonts-noto-cjk能解决。二是分辨率，CI 默认视口可能很小，建议显式设置viewport: { width: 1440, height: 900 }，和开发环境保持一致。

另外 CI 上模型调用要走内网或配置好出口，否则会超时。建议在 CI 配置里加一个健康检查步骤，先发一张测试截图确认模型可用，再跑正式用例。

6. 常见问题排查速查

6.1 模型定位不准的排查路径

现象	可能原因	排查方法	解决手段
点击了错误元素	指令描述模糊	查看模型返回的动作描述	补充区域限定词
找不到目标元素	截图时元素未渲染	检查截图内容	增加 aiWaitFor
中文识别为乱码	系统缺中文字体	查看截图文字	安装 CJK 字体
坐标偏移	页面缩放或 DPR 不一致	对比截图与实际视口	统一 viewport 与 deviceScaleFactor
动作执行超时	模型响应慢	查看网络耗时	增加超时或换本地模型

6.2 性能与成本控制

视觉驱动最大的隐性成本是模型调用。一个 20 步的用例，每步一次模型调用，单次 2 秒，就是 40 秒，加上页面加载，一个用例跑一分钟很正常。传统脚本可能只要 10 秒。

控制手段有几个：合并指令，把"点击输入框、输入内容、点击搜索"合成一条aiAction，让模型一次规划多步；缓存页面状态，相同页面结构的操作复用上一次的定位结果；分级执行，冒烟测试用视觉驱动快速覆盖，全量回归用固化脚本。

6.3 视觉驱动不适合的场景

不是所有 UI 都适合视觉驱动。高频动画页面，截图永远在变，模型判断不稳定。Canvas 或 WebGL 渲染的应用，DOM 里没有语义信息，视觉驱动反而比传统方案更合适，但需要模型有较强的图形理解能力。验证码和滑块，这类本身就是反自动化的设计，视觉驱动能做但涉及合规风险，不建议在生产测试中使用。

注意：涉及用户隐私数据的页面，截图发给云端模型前必须做脱敏处理，否则有数据泄露风险。Midscene 支持截图遮罩配置，把敏感区域涂黑再发送。

7. 我在实际项目中的几点体会

视觉驱动脚本写多了，会发现它和传统脚本不是替代关系，而是互补。我的团队现在的做法是：核心交易链路用 Playwright 原生选择器写，保证速度和稳定；营销活动页、频繁改版的页面用 Midscene 视觉驱动，保证改版后不用改脚本。两套脚本共用一套 pytest 组织和报告体系，CI 里并行跑。

另外一点，模型不是越强越好。我们试过用最强的多模态模型，识别确实准，但一个回归套件跑下来费用惊人。后来换成中等能力的模型，配合更精确的指令和局部截图，准确率只降了两个百分点，成本降了七成。指令工程省下来的钱，比换模型省得多。

最后，视觉驱动的调试体验和传统脚本完全不同。传统脚本断点一打，看变量就知道哪错了。视觉驱动出错，你得看截图、看模型返回的原始文本、看动作映射后的 Playwright 调用，三层信息对照才能定位。建议在项目初期就把这三层日志打通，否则后期排查会非常痛苦。