Midscene 完全指南一条 YAML 脚本跑通你的首个视觉 E2E 用例【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene每个测试同学都遇到过这种场景页面刚改版一批 XPath 选择器集体失效E2E 脚本接连报错。Midscene 是一个面向 E2E 测试的 GUI Agent你不需要写选择器只需用自然语言描述操作它通过截图看懂界面完成点击、输入和断言。下面从环境就绪到跑完一个完整用例带你走一遍主线。项目速览看屏幕来操作替代写死的选择器Midscene 的核心是视觉驱动每一步先截取界面交给多模态模型判断目标元素在哪里再执行点击、输入或滚动。同一套 Agent APIaiAct、aiTap、aiAssert可以在 Web、Android、iOS、HarmonyOS 和桌面端运行。与基于选择器的方案相比它不依赖 DOM 结构因此纯图标按钮、canvas和跨域 iframe 里的元素也能操作。项目还自带 YAML 脚本运行器和交互式 HTML 报告写自动化流程不必再搭建测试框架。问题场景常规做法Midscene 的做法元素定位编写 XPath/CSS 选择器页面改版后失效用自然语言描述元素从截图识别不依赖 DOM 结构视觉结果校验人工目测或截图比对用aiAssert以自然语言校验选中项有蓝色边框等可见状态跨平台覆盖每个平台单独写 Playwright/Appium 脚本同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS、桌面端模型调用成本每次执行都完整分析界面缓存 AI 规划与元素定位官方示例中单次执行从 51 秒降到 28 秒项目还内置了 Chrome 扩展版 Playground安装扩展后把模型配置粘贴进设置页就可以不写任何代码直接在浏览器里试用和调教自然语言指令。Midscene Chrome 扩展侧边栏粘贴模型配置后即可在任意网页上执行自然语言指令30 分钟上手主线从配置模型到跑通首个用例M1 环境就绪约 5 分钟先确认 Node 版本满足 CLI 的运行要求node -v # 预期20.19、22.12 或 24 npm i -g midscene/cli预期结果命令无报错midscene --help能打印参数说明。若报Unsupported Node.js version说明 Node 版本过旧Rstest/Rspack 工具链会拒绝 20.17.0 这类 20 系列旧 patch 版本升级 Node 后重装即可。然后在工具运行目录下创建.env以下面这组豆包 Seed 2.1 Turbo 的配置为例MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed 注意.env必须放在工具运行目录与 YAML 文件所在目录无关按 dotenv 约定不写export前缀它默认不覆盖已存在的同名全局环境变量。M2 首次成功运行约 5 分钟写一个最小的 Web 脚本bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息运行midscene ./bing-search.yaml --headed # 想看浏览器操作过程可加 --headed预期结果终端逐步输出执行进度完成后在midscene_run/目录生成可视化 HTML 报告可逐步回看截图与断言结果。若提示模型连接失败先用--dotenv-debug参数排查.env是否被正确加载。M3 完成一个自定义用例约 10 分钟把示例改成你自己的业务输入更精确、加等待条件、最后提取结构化数据page: url: https://www.bing.com output: ./result.json # aiQuery 结果写入该文件 tasks: - name: 搜索并提取 flow: - aiInput: 搜索框 value: 无线耳机 - aiTap: 搜索按钮 - aiWaitFor: 搜索结果页加载完成 timeout: 20000 - aiQuery: 结果页前 3 条内容{name: string}[] name: search_result预期结果result.json中出现search_result字段。若某步超时一句话排查先检查自然语言描述与实际界面文案是否对得上再看该步是否需要把timeout调大。端到端实战从一个脚本到一份可读的报告以验证搜索结果是否出现天气信息为例完整走一遍配置、执行与结果解读。背景上这类断言在传统方案里很难表达天气卡片是动态渲染的选择器随时可能变而aiAssert只关心屏幕上是否出现了天气信息这一用户视角。配置沿用 M1 的.env和 M2 的bing-search.yaml执行midscene ./bing-search.yaml默认无头模式CI 上可直接使用。执行结束后打开midscene_run/里生成的 HTML 报告做验证报告按时间线列出每一步的截图、实际操作、AI 的决策过程和aiAssert的通过情况。结果解读时重点看两处一是断言步骤的结论与原因失败时模型会说明不成立的理由二是每步耗时判断是否需要开启缓存。如果你对提示词措辞没有把握可以先在 Playground 里验证再落到脚本中。Playground 运行界面自然语言指令执行过程与结果一目了然进阶与避坑缓存、并发与高频报错缓存不生效症状重复运行用例./midscene_run/cache目录下没有生成缓存文件。 原因缓存默认关闭未配置cache选项。 解法在 YAML 的agent部分加cache: { id: 你的用例id }默认读写模式自动维护缓存文件。本地命中缓存CI 不命中症状CI 执行明显更慢报告中看不到 cache 提示。 原因./midscene_run/cache未提交到仓库CI 每次都是干净环境。 解法把缓存文件提交到仓库若仍不命中通常是页面 DOM 变化导致 XPath 校验失败Midscene 会自动回退到模型重新分析属正常行为。压缩执行时间与模型成本症状同一套用例反复执行耗时和调用费用偏高。 原因规划类步骤ai/aiAct每次都完整调用模型。 解法开启读写缓存后官方示例中单次执行从 51 秒降到 28 秒多个互不依赖的脚本用并发参数批量跑偶发失败步骤加--retry重试开启缓存后报告中的耗时对比51 秒降至 28 秒midscene --files ./scripts/search-*.yaml --concurrent 4 --continue-on-error⚠️Node 版本不兼容症状安装或运行时报Unsupported Node.js version。 原因CLI 部分执行路径依赖 Rstest/Rspack 工具链拒绝较旧的 Node 20 patch 版本。 解法升级 Node 到 20.19、22.12 或 24重新安装全局 CLI。小图标偶尔点错症状小图标或外观相近的元素偶发定位错误。 原因默认定位精度对小目标不够。 解法在该步骤加deepLocate: true增加一次定位调用复杂任务可加deepThink: true拆分规划代价是更多模型调用与延迟。.env配置不生效症状.env里写了模型配置却像被忽略。 原因文件不在工具运行目录或全局已存在同名环境变量dotenv 默认不覆盖。 解法把.env放到运行目录确需覆盖时加--dotenv-override用--dotenv-debug查看加载细节。收尾Midscene 用一次截图理解替代选择器维护一条 YAML 就能驱动 Web、移动端或桌面的完整 E2E 用例。延伸阅读YAML 脚本运行器文档核心 Agent 源码【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Midscene 完全指南：一条 YAML 脚本跑通你的首个视觉 E2E 用例
Midscene 完全指南一条 YAML 脚本跑通你的首个视觉 E2E 用例【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene每个测试同学都遇到过这种场景页面刚改版一批 XPath 选择器集体失效E2E 脚本接连报错。Midscene 是一个面向 E2E 测试的 GUI Agent你不需要写选择器只需用自然语言描述操作它通过截图看懂界面完成点击、输入和断言。下面从环境就绪到跑完一个完整用例带你走一遍主线。项目速览看屏幕来操作替代写死的选择器Midscene 的核心是视觉驱动每一步先截取界面交给多模态模型判断目标元素在哪里再执行点击、输入或滚动。同一套 Agent APIaiAct、aiTap、aiAssert可以在 Web、Android、iOS、HarmonyOS 和桌面端运行。与基于选择器的方案相比它不依赖 DOM 结构因此纯图标按钮、canvas和跨域 iframe 里的元素也能操作。项目还自带 YAML 脚本运行器和交互式 HTML 报告写自动化流程不必再搭建测试框架。问题场景常规做法Midscene 的做法元素定位编写 XPath/CSS 选择器页面改版后失效用自然语言描述元素从截图识别不依赖 DOM 结构视觉结果校验人工目测或截图比对用aiAssert以自然语言校验选中项有蓝色边框等可见状态跨平台覆盖每个平台单独写 Playwright/Appium 脚本同一套 Agent API 覆盖 Web、Android、iOS、HarmonyOS、桌面端模型调用成本每次执行都完整分析界面缓存 AI 规划与元素定位官方示例中单次执行从 51 秒降到 28 秒项目还内置了 Chrome 扩展版 Playground安装扩展后把模型配置粘贴进设置页就可以不写任何代码直接在浏览器里试用和调教自然语言指令。Midscene Chrome 扩展侧边栏粘贴模型配置后即可在任意网页上执行自然语言指令30 分钟上手主线从配置模型到跑通首个用例M1 环境就绪约 5 分钟先确认 Node 版本满足 CLI 的运行要求node -v # 预期20.19、22.12 或 24 npm i -g midscene/cli预期结果命令无报错midscene --help能打印参数说明。若报Unsupported Node.js version说明 Node 版本过旧Rstest/Rspack 工具链会拒绝 20.17.0 这类 20 系列旧 patch 版本升级 Node 后重装即可。然后在工具运行目录下创建.env以下面这组豆包 Seed 2.1 Turbo 的配置为例MIDSCENE_MODEL_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3 MIDSCENE_MODEL_API_KEYyour-api-key MIDSCENE_MODEL_NAMEdoubao-seed-2-1-turbo-260628 MIDSCENE_MODEL_FAMILYdoubao-seed 注意.env必须放在工具运行目录与 YAML 文件所在目录无关按 dotenv 约定不写export前缀它默认不覆盖已存在的同名全局环境变量。M2 首次成功运行约 5 分钟写一个最小的 Web 脚本bing-search.yamlpage: url: https://www.bing.com tasks: - name: 搜索天气 flow: - ai: 搜索 今日天气 - sleep: 3000 - aiAssert: 结果显示天气信息运行midscene ./bing-search.yaml --headed # 想看浏览器操作过程可加 --headed预期结果终端逐步输出执行进度完成后在midscene_run/目录生成可视化 HTML 报告可逐步回看截图与断言结果。若提示模型连接失败先用--dotenv-debug参数排查.env是否被正确加载。M3 完成一个自定义用例约 10 分钟把示例改成你自己的业务输入更精确、加等待条件、最后提取结构化数据page: url: https://www.bing.com output: ./result.json # aiQuery 结果写入该文件 tasks: - name: 搜索并提取 flow: - aiInput: 搜索框 value: 无线耳机 - aiTap: 搜索按钮 - aiWaitFor: 搜索结果页加载完成 timeout: 20000 - aiQuery: 结果页前 3 条内容{name: string}[] name: search_result预期结果result.json中出现search_result字段。若某步超时一句话排查先检查自然语言描述与实际界面文案是否对得上再看该步是否需要把timeout调大。端到端实战从一个脚本到一份可读的报告以验证搜索结果是否出现天气信息为例完整走一遍配置、执行与结果解读。背景上这类断言在传统方案里很难表达天气卡片是动态渲染的选择器随时可能变而aiAssert只关心屏幕上是否出现了天气信息这一用户视角。配置沿用 M1 的.env和 M2 的bing-search.yaml执行midscene ./bing-search.yaml默认无头模式CI 上可直接使用。执行结束后打开midscene_run/里生成的 HTML 报告做验证报告按时间线列出每一步的截图、实际操作、AI 的决策过程和aiAssert的通过情况。结果解读时重点看两处一是断言步骤的结论与原因失败时模型会说明不成立的理由二是每步耗时判断是否需要开启缓存。如果你对提示词措辞没有把握可以先在 Playground 里验证再落到脚本中。Playground 运行界面自然语言指令执行过程与结果一目了然进阶与避坑缓存、并发与高频报错缓存不生效症状重复运行用例./midscene_run/cache目录下没有生成缓存文件。 原因缓存默认关闭未配置cache选项。 解法在 YAML 的agent部分加cache: { id: 你的用例id }默认读写模式自动维护缓存文件。本地命中缓存CI 不命中症状CI 执行明显更慢报告中看不到 cache 提示。 原因./midscene_run/cache未提交到仓库CI 每次都是干净环境。 解法把缓存文件提交到仓库若仍不命中通常是页面 DOM 变化导致 XPath 校验失败Midscene 会自动回退到模型重新分析属正常行为。压缩执行时间与模型成本症状同一套用例反复执行耗时和调用费用偏高。 原因规划类步骤ai/aiAct每次都完整调用模型。 解法开启读写缓存后官方示例中单次执行从 51 秒降到 28 秒多个互不依赖的脚本用并发参数批量跑偶发失败步骤加--retry重试开启缓存后报告中的耗时对比51 秒降至 28 秒midscene --files ./scripts/search-*.yaml --concurrent 4 --continue-on-error⚠️Node 版本不兼容症状安装或运行时报Unsupported Node.js version。 原因CLI 部分执行路径依赖 Rstest/Rspack 工具链拒绝较旧的 Node 20 patch 版本。 解法升级 Node 到 20.19、22.12 或 24重新安装全局 CLI。小图标偶尔点错症状小图标或外观相近的元素偶发定位错误。 原因默认定位精度对小目标不够。 解法在该步骤加deepLocate: true增加一次定位调用复杂任务可加deepThink: true拆分规划代价是更多模型调用与延迟。.env配置不生效症状.env里写了模型配置却像被忽略。 原因文件不在工具运行目录或全局已存在同名环境变量dotenv 默认不覆盖。 解法把.env放到运行目录确需覆盖时加--dotenv-override用--dotenv-debug查看加载细节。收尾Midscene 用一次截图理解替代选择器维护一条 YAML 就能驱动 Web、移动端或桌面的完整 E2E 用例。延伸阅读YAML 脚本运行器文档核心 Agent 源码【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考