一套 YAML 脚本跑通 Web、Android、iOS 和桌面的 UI 自动化测试Midscene 上手实录【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midsceneMidscene 是一套视觉驱动的 UI 自动化测试工具你不用写选择器而是用自然语言描述点什么、等什么、验什么同一套脚本可以跨平台地跑在 Web、Android、iOS 和桌面应用上。下面按先跑起来、再讲清楚、最后挑场景的顺序展开。一次重构引发的维护阵痛前端同学重构了下单页面按钮换了类名弹窗从底部改到了居中还加了一层包裹容器。当晚 CI 里上百条用例集体变红修了一整天全是选择器。这个场景在 Web、Android、iOS 和桌面项目里反复上演根源在于结构选择器和界面实现绑得太死。Midscene 的出发点正是这里让用例只关心屏幕上发生了什么而不是节点长什么样。快速上手最小可运行示例先装 CLI 并配好模型 API Key环境变量名在 packages/shared/src/env/types.ts 中可以查到git clone https://gitcode.com/GitHub_Trending/mid/midscene npm i -g midscene/cli export OPENAI_API_KEYyour-key再写一个最小用例打开一个页面、点进去、断言结果web: url: https://books.toscrape.com/ tasks: - name: check-first-book flow: - aiAct: 点击页面上第一本图书的封面标题 - aiWaitFor: 图书详情页加载完成 - aiQuery: prompt: 返回 {title: string, price: number} name: book - aiAssert: 当前页面显示了图书的价格用npx midscene run指向这个文件即可执行命令细节见 packages/cli/README.mdnpx midscene run first-case.yaml跑完之后你得到三样东西任务执行日志、aiQuery落盘的 JSON 结果、以及一份可回放的执行报告。apps/report/下的报告应用就是为查看这些产物准备的apps/report/e2e/report-single.yaml 里还能看到报告的验收用例本身也是 YAML 写的。工作原理截图 → 推理 → 执行整条链路可以拆成三段流水线理解它比背 API 更有用截图采集各平台适配器负责拿到当前画面。Web 端走浏览器截图Android 通过 scrcpy 拿帧流iOS 依赖 WebDriverAgent桌面端按操作系统采集显示画面。模型推理截图连同你的自然语言指令一起交给多模态模型。模型家族在 packages/core/src/ai-model/models/registry.ts 中注册目前包括 Qwen-VL、Doubao、Gemini、UI-TARS、GLM 系列、GPT、DeepSeek、Kimi、小米 MiMo 等指令按语义拆成具体步骤定位出目标元素坐标并规划等待与校验条件。动作执行适配器把推理结果翻译成点击、输入、滑动等真实输入事件回到第 1 步重新截图形成闭环直到aiWaitFor的条件满足或超时。对应到 YAML 指令aiAct执行动作aiWaitFor等待条件成立aiQuery按结构提取数据aiAssert做断言。跨平台实践四类平台支持对比平台入口模块驱动方式典型差异Webpackages/web-integration/Playwright / Puppeteer支持 Chrome 扩展桥接模式可直接跑 JS、提取 DOM 辅助数据Androidpackages/android/scrcpy 帧流 adb 注入输入需设备调试连接分辨率随设备变化iOSpackages/ios/WebDriverAgent依赖 WDA 环境模拟器与真机配置不同桌面packages/computer/各操作系统输入与截图接口窗口焦点、多显示器是主要变量同一份打开设置 → 找到亮度 → 调高的意图四类平台上写法几乎一致改的只是顶部声明的平台段。进阶技巧模型、缓存与并行模型选择日常回归用响应快的轻量视觉模型即可图标密集、控件自定义多的界面换成 UI-TARS 这类面向界面定位优化的模型验收级断言再上更强的旗舰模型。缓存aiQuery等步骤会反复做截图 → 识别代价不小。设置环境变量MIDSCENE_CACHE开启缓存后相同输入直接复用上次结果apps/site/docs/public/cache/use-cache-time.png 展示了缓存命中前后的耗时对比。并行CLI 用--concurrent控制并发执行数默认 1见 packages/cli/src/config-factory.tsnpx midscene run cases/ --concurrent 4避坑指南五个高频问题现象aiAct找不到目标元素。排查思路先回看报告里模型实际看到的截图确认画面状态对不对再给元素加视觉锚点颜色、位置、相邻文字。解法描述从点击提交改成点击右下角蓝色的提交按钮。现象步骤中途卡住或超时。排查思路确认目标状态是否真的出现了还是页面还在加载。解法拆步骤把打开详情并等待价格出现拆成两步并给aiWaitFor留足时间余量。现象aiQuery返回结构与预期不符。排查思路检查 prompt 里的结构描述是否明确。解法给出精确的 JSON 结构声明而不是返回商品信息这类模糊说法。现象同一用例在 Android 上偶尔失败。排查思路看失败截图的设备分辨率与缩放。解法固定设备分辨率或在描述里使用相对位置而非绝对像素。现象并行跑多了报模型侧限流。排查思路对照--concurrent值与 API 配额。解法调低并发或在用例间加退避。适用范围与选型建议适合回归测试和验收类场景尤其是界面频繁变动、选择器维护成本高的项目从界面上提取结构化数据aiQuery跨端一致性巡检同一意图跑多平台。不适合对毫秒级时序敏感的操作、纯性能压测、依赖可访问性树做合规校验的场景另外每次执行都有模型调用成本超大规模全量回归前建议先评估调用量。把选择器维护从日常负担里拿出来换成一句自然语言——这是 Midscene 换来的最直接收益。是否引入取决于你的界面变动频率和模型成本预算跑通上面那个最小用例一天之内就能有答案。【免费下载链接】midsceneGUI Agent for E2E Testing项目地址: https://gitcode.com/GitHub_Trending/mid/midscene创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
