企业官网建设流程全解析

Maestro AI 如何 5 分钟跑通 UI 缺陷检测与文本提取：三条 YAML 命令上手

【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro

每个版本上线前，UI 回归往往靠人肉逐页翻找：按钮错位没有？文字截断没有？字号是否小到看不清？半天时间耗过去，结论还停留在“看起来没问题”。Maestro 的 AI 功能把这件事变成三条 YAML 命令：assertNoDefectsWithAI 让 AI 自动检查当前屏幕的视觉缺陷，extractTextWithAI 把验证码、余额这类文本直接提取成变量。不用改一行代码，会写 YAML 的测试同学就能用。

一页速览：三条 AI 命令各管什么

三者都走云端：Maestro 截屏后发给 AI 服务（API，即 Application Programming Interface，服务端提供的接口），拿到结果再写回流程。区别只在输入输出形态，配置方式一致。

用 assertNoDefectsWithAI 跑通首次 UI 缺陷检测

设计改版或布局调整后，传统断言只能验证“元素在不在”，发现不了元素重叠、文字被截掉、对比度过低这类问题。assertNoDefectsWithAI 就是为此准备的，不接收任何参数，写一行即可让当前画面被完整检查一次。

原理一句话：Maestro 把当前屏幕截图发往云端 find-defects 接口，服务返回缺陷列表，每条缺陷带 category（类别）和 reasoning（判断理由），列表非空则流程判为失败，接口定义见 IAPredictionEngine.kt。

最小可运行示例：

- assertNoDefectsWithAI

用 assertWithAI 把语义断言写成一句话

想验证的有时不是“元素在不在”，而是“画面合不合理”：同一屏优惠券卡片不应超过两张、页面上不应残留加载动画。这类判断用元素选择器写起来很吃力。

assertWithAI 把断言字符串和截图一起送到同一个云端接口（源码中对应 performAssertion 方法），服务按断言判断是否存在缺陷，存在则流程失败，理由可直接用于报告。

最小写法是一行内联命令：- assertWithAI: "页面布局正常，无文字截断或元素重叠"

用 extractTextWithAI 把动态文本变成变量

验证码、余额、订单号每次都动态生成，没法写死在脚本里；传统 OCR（Optical Character Recognition，光学字符识别，即从图片中识别文字的技术）虽然能读出全部文字，却分不清你要的是哪一段。

extractTextWithAI 用自然语言指明目标：query 描述要什么，服务从截图中提取对应字符串，流程再把它写入 outputVariable 指定的变量，后续命令用双花括号引用。完整流程放在下一节，核心就这三行：

- extractTextWithAI: query: "提取页面上显示的用户余额" outputVariable: userBalance

端到端：从 0 到 1 搭一个最小 AI 校验流程

把前文能力合成一条完整流程：启动应用、等待页面稳定、缺陷检测、提取订单号并输出。

- launchApp: com.example.shop - extendedWaitUntil: until: assertVisible: "订单提交成功" - assertNoDefectsWithAI - extractTextWithAI: query: "提取页面上的订单号" outputVariable: orderNo - log: "订单号: {{orderNo}}"

决定成败的是三处。第一，API 密钥环境变量要在执行前配好，密钥的获取与导出方式见 maestro-ai/README.md，缺了密钥 AI 步骤无从发起。第二，extendedWaitUntil 等“订单提交成功”出现后才执行 AI 步骤，避免在动画途中截屏。第三，outputVariable 与 {{orderNo}} 是配套关系：提取值先落到变量，再由 log 及后续断言引用。

超时与成本：用三个字段控制 AI 请求行为

三项均为 ApiClient.kt 中的默认配置。60 秒偏保守，CI 里含 AI 步骤的整步超时要留足余量。

三条可直接照做的建议：

1. 每个 AI 步骤前加一步 extendedWaitUntil 或 waitForAnimationToEnd，让截图停在稳定帧，减少误报和浪费的计费请求。
2. query 写到元素级：“提取页面上的订单号”优于“提取那个号码”，服务返回更准，变量值更稳定。
3. CI 里只对核心页面（首页、下单页、个人页）执行 assertNoDefectsWithAI，AI 调用按截图计费，控制覆盖面就是控制成本。

常见问题

AI 步骤不生效：先查密钥环境变量

AI 引擎只在密钥非空时才被构建（源码中为apiKey?.let { ... }写法），缺密钥时 AI 步骤会直接失败。最快自查方式是在执行环境确认密钥变量已导出，demo 使用的变量名为 MAESTRO_CLI_AI_KEY，详见 maestro-ai/README.md。

检测结果时好时坏：截图截在了动画帧

加载转圈、过渡帧、半弹出的浮窗都会进截图，AI 会把这类瞬态画面判成缺陷。解法固定：在 AI 步骤前加 extendedWaitUntil 或 waitForAnimationToEnd，等画面稳定再检测。

缺陷检测通过不等于功能正确

缺陷检测只看视觉层：重叠、截断、对比度。按钮在但点了不跳转这类业务错误不在它的职责范围内，不要用它替代功能断言，两者应一起写进同一条流程。

把“人眼看 UI”这件事搬进脚本，是 Maestro AI 三条命令的核心价值；安装、构建与 demo 运行方式参见 maestro-ai/README.md。

【免费下载链接】MaestroPainless E2E Automation for Mobile and Web项目地址: https://gitcode.com/GitHub_Trending/ma/Maestro