Web自动化工具Midscene整理

Web自动化测试Midscene一、官网简介官网Midscene.js - AI 驱动带来愉悦的 UI 自动化体验 - Midscene - Vision-Driven UI Automation二、Yaml脚本运行器YAML 脚本运行器Midscene 定义了一种 YAML 格式的脚本方便开发者快速编写自动化脚本并提供了对应的命令行工具来快速执行这些脚本。举例来说你可以编写如下 YAML 格式脚本示例web: url: https://www.bing.com ​ tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息并通过一条命令来执行它midscene ./bing-search.yaml命令行会输出执行进度并在完成后生成可视化报告。整个运行过程大幅简化了开发者做环境配置的复杂度。使用.env配置环境变量Midscene 命令行工具使用 dotenv 来加载.env文件。你可以在工具运行目录下创建一个.env文件并添加以下配置MIDSCENE_MODEL_BASE_URLhttps://替换为你的模型服务地址/v1 MIDSCENE_MODEL_API_KEY替换为你的 API Key MIDSCENE_MODEL_NAME替换为你的模型名称 MIDSCENE_MODEL_FAMILY替换为你的模型系列安装命令行工具全局安装midscene/cli推荐新手使用npm i -g midscene/cli或在项目中按需安装npm i midscene/cli --save-dev编写第一个脚本编写一个名为bing-search.yaml的文件来驱动 Web 浏览器web: url: https://www.bing.com ​ tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息运行脚本midscene ./bing-search.yaml # 如果在项目中安装了 Midscene npx midscene ./bing-search.yaml命令行会输出执行进度并在完成后生成可视化报告。三、Yaml格式的工作流使用 YAML 格式的自动化脚本在大多数情况下开发者编写自动化脚本只是为了执行一些简单流程比如检查某些内容是否出现或者验证某个关键用户路径是否可用。此时维护一个大型测试项目会显得毫无必要。⁠Midscene 提供了一种基于.yaml文件的自动化测试方法这有助于你专注于编写流程而不是测试框架。这里有一个示例通过阅读它的内容你应该已经理解了它的工作原理。web: url: https://www.bing.com ​ tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 ​ - name: 检查结果 flow: - aiAssert: 结果中展示了天气信息agent部分agent部分用于配置 AI Agent 的行为和测试报告相关选项。所有字段都是可选的。# AI agent 配置 agent: # 测试标识符用于报告和缓存识别可选 testId: string ​ # 报告组名称可选 groupName: string ​ # 报告组描述可选 groupDescription: string ​ # 是否生成测试报告可选默认 true generateReport: boolean ​ # 是否自动打印报告消息可选默认 true autoPrintReportMsg: boolean ​ # 自定义报告文件名可选 reportFileName: string ​ # AI 最大重规划循环次数可选默认 20UI-TARS 模型为 40 replanningCycleLimit: number ​ # 在调用 aiAct 时发送给 AI 模型的背景知识可选 aiActContext: string # 兼容的旧字段aiActionContext仍可使用但不推荐 ​ # 缓存配置可选 cache: # 缓存策略可选可选值read-only | read-write | write-only strategy: string # 缓存 ID必填 id: stringweb部分web: # 访问的 URL必填。如果提供了 serve 参数则提供相对路径 url: url # 在本地路径下启动一个静态服务可选 serve: root-directory # 浏览器 UA可选 userAgent: ua # 浏览器视口宽度可选默认 1280 viewportWidth: width # 浏览器视口高度可选默认 960 viewportHeight: height # 浏览器设备像素比可选默认跟随系统 deviceScaleFactor: scale # JSON 格式的浏览器 Cookie 文件路径可选 cookie: path-to-cookie-file # 等待网络空闲的策略可选 waitForNetworkIdle: # 等待超时时间可选默认 2000ms timeout: ms # 是否在等待超时后继续可选默认 true continueOnNetworkIdleError: boolean # 输出 aiQuery/aiAssert 结果的 JSON 文件路径可选 output: path-to-output-file # 是否保存日志内容到 JSON 文件可选默认 false。如果为 true保存到 unstableLogContent.json 文件中。如果为字符串则保存到该字符串指定的路径中。日志内容的结构可能会在未来发生变化。 unstableLogContent: boolean | path-to-unstable-log-file # 是否限制页面在当前 tab 打开可选默认 true forceSameTabNavigation: boolean # CDP 连接端点可选。设置后通过 CDP 连接到已有浏览器实例而非启动新浏览器。 # 与 bridgeMode 互斥不可同时使用。 cdpEndpoint: ws://localhost:9222/devtools/browser # 桥接模式可选默认 false可以为 newTabWithUrl 或 currentTab。更多详情请参阅后文 bridgeMode: false | newTabWithUrl | currentTab # 是否在桥接断开时关闭新创建的标签页可选默认 false closeNewTabsAfterDisconnect: boolean # 是否忽略 HTTPS 证书错误可选默认 false acceptInsecureCerts: boolean # 自定义 Chrome 启动参数仅 Puppeteer 模式不支持桥接模式可选 # 用于自定义 Chrome 浏览器行为例如禁用第三方 Cookie 阻止 # ⚠️ 安全警告某些参数如 --no-sandbox、--disable-web-security可能降低浏览器安全性 # 仅在受控的测试环境中使用 chromeArgs: - --disable-featuresThirdPartyCookiePhaseout - --disable-featuresSameSiteByDefaultCookies - --window-size1920,1080tasks部分tasks部分是一个数组定义了脚本执行的步骤。记得在每个步骤前添加-符号表明这些步骤是个数组。flow部分的接口与 API 几乎相同除了一些参数的嵌套层级。tasks: - name: name continueOnError: boolean # 可选错误时是否继续执行下一个任务默认 false flow: # 自动规划(Auto Planning, .ai) # ---------------- # 执行一个交互ai 是 aiAct 的简写方式 - ai: prompt cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时,是否允许缓存当前 API 调用结果。默认值为 True deepThink: boolean # 可选当模型支持时取决于 MIDSCENE_MODEL_FAMILY开启规划阶段的深度思考能力。默认值为 undefined跟随模型服务商的默认策略。 # 这种用法与 ai 相同 # 注意在之前版本中也被写作 aiAction当前版本兼容两种写法 - aiAct: prompt cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时是否允许缓存当前 API 调用结果。默认值为 True deepThink: boolean # 可选当模型支持时取决于 MIDSCENE_MODEL_FAMILY开启规划阶段的深度思考能力。默认值为 undefined跟随模型服务商的默认策略。 # 即时操作(Instant Action, .aiTap, .aiHover, .aiInput, .aiKeyboardPress, .aiScroll) # ---------------- # 点击一个元素用 prompt 描述元素位置 - aiTap: prompt deepThink: boolean # 可选是否使用深度思考deepThink来精确定位元素。默认值为 False xpath: xpath # 可选目标元素的 xpath 路径用于执行当前操作。如果提供了这个 xpathMidscene 会优先使用该 xpath 来找到元素然后依次使用缓存和 AI 模型。默认值为空 cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时是否允许缓存当前 API 调用结果。默认值为 True fileChooserAccept: path | [path1, path2] # 可选当点击触发文件选择器时指定要上传的文件路径仅在 web 中可用 # 鼠标悬停一个元素用 prompt 描述元素位置 - aiHover: prompt deepThink: boolean # 可选是否使用深度思考deepThink来精确定位元素。默认值为 False xpath: xpath # 可选目标元素的 xpath 路径用于执行当前操作。如果提供了这个 xpathMidscene 会优先使用该 xpath 来找到元素然后依次使用缓存和 AI 模型。默认值为空 cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时是否允许缓存当前 API 调用结果。默认值为 True # 输入文本到一个元素用 prompt 描述元素位置 - aiInput: prompt # 要输入文本的元素 value: 输入框的最终文本内容 deepThink: boolean # 可选是否使用深度思考deepThink来精确定位元素。默认值为 False xpath: xpath # 可选目标元素的 xpath 路径用于执行当前操作。如果提供了这个 xpathMidscene 会优先使用该 xpath 来找到元素然后依次使用缓存和 AI 模型。默认值为空 cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时是否允许缓存当前 API 调用结果。默认值为 True # 在元素上按下某个按键如 EnterTabEscape 等用 prompt 描述元素位置 - aiKeyboardPress: prompt # 要按键的目标元素 keyName: 按键 deepThink: boolean # 可选是否使用深度思考deepThink来精确定位元素。默认值为 False xpath: xpath # 可选目标元素的 xpath 路径用于执行当前操作。如果提供了这个 xpathMidscene 会优先使用该 xpath 来找到元素然后依次使用缓存和 AI 模型。默认值为空 cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时是否允许缓存当前 API 调用结果。默认值为 True # 全局滚动或滚动 prompt 描述的元素 - aiScroll: prompt # 可选执行滚动的元素 scrollType: singleAction # 或 scrollToBottom | scrollToTop | scrollToRight | scrollToLeft默认值为 singleAction direction: down # 或 up | left | right默认值为 down。仅在 scrollType 为 singleAction 时生效 distance: number # 可选滚动距离单位为像素。设置为 null 表示由 Midscene 自动决定。 deepThink: boolean # 可选是否使用深度思考deepThink来精确定位元素。默认值为 False xpath: xpath # 可选目标元素的 xpath 路径用于执行当前操作。如果提供了这个 xpathMidscene 会优先使用该 xpath 来找到元素然后依次使用缓存和 AI 模型。默认值为空 cacheable: boolean # 可选当启用 [缓存功能](./caching.mdx) 时是否允许缓存当前 API 调用结果。默认值为 True # 在报告文件中记录当前截图并添加描述 - recordToReport: title # 可选截图的标题如果未提供则标题为 untitled content: content # 可选截图的描述 # 数据提取 # ---------------- # 执行一个查询返回一个 JSON 对象 - aiQuery: prompt # 记得在提示词中描述输出结果的格式 name: name # 查询结果在 JSON 输出中的 key # 更多 API # ---------------- # 等待某个条件满足并设置超时时间(ms可选默认 30000) - aiWaitFor: prompt timeout: ms # 执行一个断言 - aiAssert: prompt errorMessage: error-message # 可选当断言失败时打印的错误信息。 name: name # 可选给断言一个名称会在 JSON 输出中作为 key 使用 # 等待一定时间 - sleep: ms # 在 web 页面上下文中执行一段 JavaScript 代码 - javascript: javascript name: name # 可选给返回值一个名称会在 JSON 输出中作为 key 使用 - name: name flow: # ...四、集成PlayWrghtPlaywright负责浏览器控制打开、点击、输入、截图Midscene负责AI 视觉理解看页面、找元素、判断、智能操作Python负责流程、逻辑、断言、串联一切你现在的技术栈完美兼容直接合体1. 最简集成代码复制就能跑先安装依赖pip install playwright midscene-python playwright install chrome2. 完整集成示例最标准写法from playwright.sync_api import sync_playwright from midscene import MidsceneAI # 1. 启动浏览器Playwright 控制 with sync_playwright() as p: browser p.chromium.launch(headlessFalse) page browser.new_page( viewport{width: 1920, height: 1080} # 解决你之前元素太大的问题 ) # 打开页面 page.goto(https://test.lumiyao.com/) # 2. 初始化 Midscene AI绑定 page ai MidsceneAI(page) # # 3. 组合使用Playwright AI # # AI 输入账号 ai.ai_input(用户名输入框, gch) # AI 输入密码 ai.ai_input(密码输入框, tuoWayYao2025) # AI 点击登录 ai.ai_tap(登录按钮) # AI 断言你最关心的失败不中断 try: ai.ai_assert(页面显示登录成功) print(✅ 登录成功) except Exception as e: print(❌ 登录失败但继续执行, e) # Playwright 普通操作不占 token超快 page.wait_for_timeout(2000) page.screenshot(pathsuccess.png) browser.close()3. 你能获得的 4 个超级好处1完全可控流程、循环、条件、重试、断言、异常捕获全由 Python 控制再也不受 YAML 限制2省 Token 神器能不用 AI 就用 Playwright 原生click、fill、type必须用智能识别时才调用ai_tap / ai_input3断言失败不中断Pythontry-except随便写想怎么继续就怎么继续。4页面大小、比例、缩放 100% 可控你之前的元素太大、布局异常问题在 Python 里一行解决page browser.new_page( viewport{width: 1366, height: 768}, device_scale_factor1 # 解决元素放大 )4. 最常用 API 对照表你一看就会功能Python Midscene 写法说明点击ai.ai_tap (登录)AI 视觉点击输入ai.ai_input (账号, xxx)AI 定位输入右键ai.ai_right_click (菜单)右键断言ai.ai_assert (出现成功提示)AI 判断普通点击page.click(#login)原生不占 token普通输入page.fill(#user, xxx)原生超快5. 你一定会问的关键问题Q1Python 版 Midscene 收费 / Token 一样吗完全一样只是语言不同模型调用一致。Q2能做性能测试吗能Python Locust Playwright Midscene四合一压测 自动化一体。Q3元素太大、乱码、中断问题能解决吗全部能解决Python 里可以精确控制视口、编码、异常。五、Midscene如何节省tokenMidscene 没有不带ai前缀的纯坐标 / 选择器操作如tap/rightClick/input所有直接操作都以ai开头。但它提供了非规划式、单次执行的即时操作 API可大幅减少 Token 消耗。1. 常用即时操作非 aiAct 多步规划这些是你要找的 “普通操作” 等价写法只做一次定位 执行不做多步 AI 规划操作API / 关键字说明点击aiTap找到元素并点击最常用右键点击aiRightClick右键点击目标元素双击aiDoubleClick双击目标元素输入aiInput定位输入框并输入文本悬停aiHover鼠标悬停在元素上滚动aiScroll滚动页面 / 元素键盘按键aiKeyboardPress发送键盘事件如 Enter2. 代码示例JS/TSimport { createPlaywrightAgent } from midscene/web; const agent await createPlaywrightAgent({ browserType: chromium, headless: false, }); await agent.goto(https://example.com); // 1. 普通点击等价于 tap await agent.aiTap(登录按钮); // 2. 右键点击 await agent.aiRightClick(文件列表中的第一个文件); // 3. 输入等价于 input await agent.aiInput(搜索框, { value: midscene }); // 4. 双击 await agent.aiDoubleClick(桌面图标); // 5. 悬停 await agent.aiHover(用户头像);3. YAML 写法直接在任务中使用tasks: - name: 打开页面 go: https://example.com - name: 点击登录普通点击 aiTap: 登录按钮 # 直接用 aiTap不是 ai: 点击... - name: 输入账号 aiInput: target: 用户名输入框 value: testuser - name: 右键菜单 aiRightClick: 右上角用户头像4. 关键区别为什么用 aiTap 而不是 aiaiTap/aiInput单次操作只做一次视觉定位 执行Token 消耗低、速度快。ai: 点击xxx进入AI 多步规划模式会反复调用模型Token 消耗高。5. 如何进一步省 Token你最关心的优先用aiTap/aiInput少用aiAct/ai: xxx。描述尽量精准减少 AI 推理成本。开启截图压缩与 DOM 简化之前给你的配置。