大模型 UI 自动化测试项目文档
项目：AI_AUTO_TEST
测试对象：闪电 AI / 斑马百科安卓端
框架：Midscene 视觉大模型框架
模型：Qwen3VLFlash
一、项目概述
1.1 项目介绍
本项目是基于Midscene 视觉大模型框架的 UI 自动化测试解决方案，用于对「闪电 AI」自动化回归测试。
核心优势：
✅无需控件树：直接通过截图识别 UI 元素
✅自然语言驱动：用人类语言描述测试步骤
✅智能缓存：二次运行显著提速，降低成本
✅全自动化：测试 → 报告 → 邮件通知一键完成
1.2 技术架构
测试脚本 (YAML) → Midscene CLI → 视觉大模型 (Qwen3VL) → ADB 执行 → 生成报告 → 邮件通知
二、Midscene 框架介绍
2.1 什么是 Midscene
Midscene 是基于「视觉多模态大模型 + 自然语言描述」的 UI 自动化框架。与 Appium/UIAutomator 不同，不依赖控件树，而是让视觉大模型直接「看截图 → 理解画面 → 规划动作」。
工作原理：
1. 截取当前屏幕
2. 将截图发送给视觉大模型
3. 模型理解画面并定位目标元素
4. 生成具体坐标或操作指令
5. 通过 ADB 执行动作
2.2 核心 YAML 指令
| 指令 | 功能 | 示例 |
| `ai` / `aiAct` | 自由形式自然语言操作 | 「在输入框中输入『今天天气怎么样』」 |
| `aiTap` | 精准点击某个元素 | 「顶部当前可见的返回按钮」 |
| `aiInput` | 文本输入 | 向输入框填入问题 |
| `aiKeyboardPress` | 键盘按键 | 按 Enter 发送 |
| `aiScroll` | 纵向滚动指定区域 | 分段滑动列表 |
| `aiWaitFor` | 自然语言等待条件 | 等待 AI 回复的气泡出现 |
| `aiAssert` | 自然语言断言 | 「卡片上方出现『节选自』文字」 |
| `sleep` | 等待指定时间 | `sleep: 2000` (2秒) |
| `launch` | 启动 App | `launch: com.fenbi.android.pedia` |
⚠️ 重要提示： 报告中的「断言明细」只来自带 `name` 的 `aiAssert`。`aiWaitFor` 超时不会写入 JSON 断言。
2.3 使用的大模型
配置文件：`.env`
MIDSCENE_MODEL_BASE_URL="https://conanaiplatform.zhenguanyu.com/litellm/"
MIDSCENE_MODEL_API_KEY="sk*"
MIDSCENE_MODEL_NAME="qwen3vlflash"
MIDSCENE_MODEL_FAMILY="qwen3vl"
使用公司内部LiteLLM 网关统一代理
当前主用Qwen3VLFlash（视觉多模态模型）
截图缩小到 30%（`screenshotResizeScale: 0.3`），降低 token 成本并提高响应速度
三、项目目录结构
AI_AUTO_TEST/
├── README.md 快速上手指南
├── .env 大模型网关/Key/模型名配置
│
├── IntoApp.yaml 「进入 App」前置流程
├── ShanDiantest.yaml 【测试环境】闪电 AI 回归测试主脚本
├── ShanDian.yaml 【线上环境】闪电 AI 回归测试主脚本
├── test.yaml 小流程验证用
├── scripts/ 编排脚本
│ ├── run_yaml_then_report_then_email.sh 【核心】一键编排
│ ├── run_yaml_by_task_name.py 按 tasks[].name 子集跑
│ ├── generate_midscene_email_report.py 生成 HTML 简报
│ └── send_midscene_report_email.py 发邮件
│
└── midscene_run/ Midscene 运行时产物
├── cache/ 视觉定位缓存
├── output/ summary*.json + 断言明细
├── report/ Midscene 原生完整 HTML 报告
├── log/ 细分日志
└── latesttestreport.html 【发送邮件 HTML 简报】
四、缓存机制详解
4.1 缓存的作用
⚡加速二次运行：首次运行后，后续运行直接使用缓存的定位方案
💰降低成本：减少大模型调用次数
📊提高稳定性：避免模型理解偏差导致的抖动
4.2 缓存配置
在 YAML 顶部配置：
yaml
agent:
cache:
id: "shandiantestcache"
strategy: "readwrite"
单个指令控制：
yaml
aiTap: 顶部的搜索框
cacheable: false 不使用缓存，每次都调用大模型
4.3 缓存文件
缓存存储在 `midscene_run/cache/*.cache.yaml`，格式示例：
yaml
step: 1
instruction: "顶部的搜索框"
result:
x: 360
y: 120
建议：
✅ 固定 UI 元素使用缓存（如顶栏按钮）
❌ 动态内容不使用缓存（如弹窗、活动提示）
五、测试用例编写指南
5.1 YAML 脚本结构
yaml
android:
deviceId: emulator5554 设备 ID
launch: com.fenbi.android.pedia App 包名
screenshotResizeScale: 0.3 截图缩小到 30%
agent:
cache:
id: "testcache"
strategy: "readwrite"
tasks:
name: 任务名称
continueOnError: false 失败是否继续
flow:
aiTap: 顶部的搜索框
aiInput: 今天天气怎么样
aiKeyboardPress: Enter
aiWaitFor: 页面加载完成，显示回复内容
timeout: 15000
aiAssert: 回复内容包含天气信息
5.2 典型场景示例
场景 1：处理弹窗
yaml
name: 首页可选关闭遮挡弹窗
continueOnError: false
flow:
ai: 若在屏幕下面有弹窗，若仅有右上角小「X」,点击「X」。若当前没有遮挡弹窗，不要点击。
cacheable: false
场景 2：权限申请
yaml
name: 录音可选允许弹窗
flow:
ai: 先根据当前截图判断是否出现系统权限类弹窗。仅当确实存在此类弹窗且上面有「允许」「同意」等按钮时，再点击；若没有权限弹窗，则不要执行任何点击。
cacheable: false
场景 3：滚动查找
yaml
name: 向下滑动寻找目标
flow:
aiScroll:
direction: down
distance: medium
aiWaitFor: 找到目标元素
5.3 按任务名筛选执行
使用 `run_yaml_by_task_name.py` 只运行指定任务：
bash
单个任务
python3 scripts/run_yaml_by_task_name.py ShanDian.yaml "断言录音弹窗"
多个任务（任一匹配即选中，按顺序执行）
python3 scripts/run_yaml_by_task_name.py ShanDian.yaml "录音 输入"
六、测试报告生成
6.1 Midscene 原生报告
位置：`midscene_run/report/midscenexxx.html`
完整的 HTML 报告（单文件几百 MB）
包含所有截图、日志、调用链
适合详细排查问题
6.2 精简 HTML 简报
位置：`midscene_run/latesttestreport.html`
由 `generate_midscene_email_report.py` 自动生成，包含：
报告内容：
📊 测试概览（通过率、耗时、模型信息）
✅ 断言明细表格（名称、结果、耗时）
❌ 失败原因分析（日志片段）
📝 最后执行步骤（便于定位中断位置）
七、邮件通知系统
如下截图:
数据来源：
`midscene_run/output/summary*.json` 测试概览
`midscene_run/output/<脚本><时间戳>.json` 断言明细
`midscene_run/log/yamlplayer.log` 执行流程
`midscene_run/log/aicall.log` AI 调用记录
手动生成报告：
python3 scripts/generate_midscene_email_report.py
手动发送邮件：
python3 scripts/send_midscene_report_email.py
八、一键编排脚本
8.1 核心脚本：run_yaml_then_report_then_email.sh
完整流程：
1. ✅ 进入 App（IntoApp.yaml）
2. ✅ 执行主测试（ShanDiantest.yaml）
3. ✅ 生成测试报告
4. ✅ 发送邮件通知
用法：
bash
基础用法（使用默认配置）
./scripts/run_yaml_then_report_then_email.sh
指定测试脚本
./scripts/run_yaml_then_report_then_email.sh ShanDiantest.yaml
跳过「进入 App」步骤（调试用）
SKIP_INTO_APP=1 ./scripts/run_yaml_then_report_then_email.sh ShanDiantest.yaml
8.2 Jenkins 集成
在 Jenkins 中创建 Shell 构建步骤：
bash
!/bin/bash
cd /path/to/AI_AUTO_TEST
设置环境变量
export MIDSCENE_CMD="npx midscene"
执行测试
./scripts/run_yaml_then_report_then_email.sh ShanDiantest.yaml
九、日志系统
9.1 日志文件分类
| 日志文件 | 内容 | 用途 |
| `yamlplayer.log` | 执行流程日志 | 定位最后执行步骤、查看任务顺序 |
| `aicall.log` | AI 调用日志 | 查看模型调用次数、token 消耗 |
| 其他日志 | 细分日志（agent、debug 等） | 深度调试 |
9.2 查看最后执行步骤
当测试中断时，查看 `yamlplayer.log` 最后的 `playing step` 日志：
playing step 12, flowItem={"aiTap": "底部右侧的键盘切换图标"}
这帮助快速定位中断位置。
9.3 AI 调用统计
查看 `aicall.log` 统计大模型调用次数和 token 消耗，优化测试脚本。
十、环境配置
10.1 依赖安装
Node.js 环境：
bash
npm install @midscene/cli
npm install @midscene/android
Python 环境：
bash
pip install pyyaml
Android 工具：
安装 ADB
安装 Android SDK
10.2 设备配置
Android 模拟器：
bash
启动模拟器
emulator avd <模拟器名称>
查看设备 ID
adb devices
在 YAML 中配置
android:
deviceId: emulator5554
真机连接：
bash
启用 USB 调试
连接设备后查看 ID
adb devices
配置设备 ID
android:
deviceId: <真机ID>
10.3 模型配置
编辑 `.env` 文件：
bash
MIDSCENE_MODEL_BASE_URL="https://conanaiplatform.zhenguanyu.com/litellm/"
MIDSCENE_MODEL_API_KEY="skyourapikey"
MIDSCENE_MODEL_NAME="qwen3vlflash"
MIDSCENE_MODEL_FAMILY="qwen3vl"
切换模型（如 Doubao Seed）：
bash
注释当前模型，取消注释目标模型
MIDSCENE_MODEL_NAME="qwen3vlflash"
MIDSCENE_MODEL_NAME="doubaoseed2.0pro260215"
MIDSCENE_MODEL_FAMILY="doubaoseed"
十一、最佳实践
11.1 测试用例编写建议
✅合理使用缓存
固定 UI 元素（如顶栏按钮）使用缓存
动态内容（如弹窗）设置 `cacheable: false`
✅错误容忍策略
弹窗处理设置 `continueOnError: false`
关键流程失败应立即停止
✅自然语言描述技巧
描述清晰具体：「顶部当前可见的返回按钮」比「返回按钮」更准确
包含条件判断：「若有弹窗则点击，没有则不操作」
11.2 性能优化
⚡截图缩放
yaml
screenshotResizeScale: 0.3 降低到 30%，加快响应速度
⚡减少不必要的 AI 调用
使用 `sleep` 代替简单等待
固定延迟用 `runAdbShell` 直接执行 ADB 命令
⚡缓存策略优化
首次运行后检查缓存命中率
调整 `cacheable` 配置
11.3 稳定性提升
🛡️弹窗处理
多次重复处理弹窗（避免遗漏）
使用条件判断（「若有则点击，没有则不操作」）
🛡️超时时间设置
yaml
aiWaitFor: 页面加载完成
timeout: 15000 根据实际情况调整
🛡️分段验证
将长流程拆分为多个 task
每个 task 添加明确的 `name`
十二、常见问题
12.1 Midscene 相关
Q: 元素定位失败怎么办？
检查自然语言描述是否准确
查看当前截图，确认元素可见
尝试设置 `cacheable: false` 重新识别
Q: AI 理解错误？
优化自然语言描述，添加更多上下文
检查截图是否清晰（缩放比例是否合适）
考虑切换模型（Qwen3VL ↔ Doubao Seed）
Q: 超时问题？
增加 `timeout` 时间
检查网络连接
确认设备性能正常
12.2 设备相关
Q: ADB 连接失败？
bash
重启 ADB 服务
adb killserver
adb startserver
检查设备连接
adb devices
Q: App 启动失败？
确认包名正确
检查 App 是否已安装
查看设备存储空间
12.3 报告与邮件
Q: 报告生成失败？
检查 `midscene_run/output/` 目录下是否有 `summary*.json`
查看 Python 脚本执行日志
Q: 邮件发送失败（535 authentication failed）？
确认使用的是「客户端专用密码」，不是网页登录密码
检查企业邮箱是否开启了 SMTP 功能
等待几分钟后重试（可能是服务器繁忙）
Q: 附件过大发送失败？
设置 `ATTACH_MIDSCENE_REPORT = False` 不发送附件
只发送精简 HTML 简报
附录
A. 常用命令速查
bash
安装依赖
npm install @midscene/android savedev
pip install pyyaml
运行测试
midscene ShanDiantest.yaml
按任务名筛选
python3 scripts/run_yaml_by_task_name.py ShanDian.yaml "录音"
一键执行
./scripts/run_yaml_then_report_then_email.sh
生成报告
python3 scripts/generate_midscene_email_report.py
发送邮件
python3 scripts/send_midscene_report_email.py
查看设备
adb devices
重启 ADB
adb killserver && adb startserver
B. 相关链接
Midscene 官方文档：https://midscenejs.com/
测试用例集：https://capas.zhenguanyu.com//cases/edit/19177
项目路径：`/Users/kanyun/.jenkins/workspace/自动化测试/AI_AUTO_TEST`
大模型 UI 自动化测试项目文档
项目：AI_AUTO_TEST
测试对象：闪电 AI / 斑马百科安卓端
框架：Midscene 视觉大模型框架
模型：Qwen3VLFlash
一、项目概述
1.1 项目介绍
本项目是基于Midscene 视觉大模型框架的 UI 自动化测试解决方案，用于对「闪电 AI」自动化回归测试。
核心优势：
✅无需控件树：直接通过截图识别 UI 元素
✅自然语言驱动：用人类语言描述测试步骤
✅智能缓存：二次运行显著提速，降低成本
✅全自动化：测试 → 报告 → 邮件通知一键完成
1.2 技术架构
测试脚本 (YAML) → Midscene CLI → 视觉大模型 (Qwen3VL) → ADB 执行 → 生成报告 → 邮件通知
二、Midscene 框架介绍
2.1 什么是 Midscene
Midscene 是基于「视觉多模态大模型 + 自然语言描述」的 UI 自动化框架。与 Appium/UIAutomator 不同，不依赖控件树，而是让视觉大模型直接「看截图 → 理解画面 → 规划动作」。
工作原理：
1. 截取当前屏幕
2. 将截图发送给视觉大模型
3. 模型理解画面并定位目标元素
4. 生成具体坐标或操作指令
5. 通过 ADB 执行动作
2.2 核心 YAML 指令
| 指令 | 功能 | 示例 |
| `ai` / `aiAct` | 自由形式自然语言操作 | 「在输入框中输入『今天天气怎么样』」 |
| `aiTap` | 精准点击某个元素 | 「顶部当前可见的返回按钮」 |
| `aiInput` | 文本输入 | 向输入框填入问题 |
| `aiKeyboardPress` | 键盘按键 | 按 Enter 发送 |
| `aiScroll` | 纵向滚动指定区域 | 分段滑动列表 |
| `aiWaitFor` | 自然语言等待条件 | 等待 AI 回复的气泡出现 |
| `aiAssert` | 自然语言断言 | 「卡片上方出现『节选自』文字」 |
| `sleep` | 等待指定时间 | `sleep: 2000` (2秒) |
| `launch` | 启动 App | `launch: com.fenbi.android.pedia` |
⚠️ 重要提示： 报告中的「断言明细」只来自带 `name` 的 `aiAssert`。`aiWaitFor` 超时不会写入 JSON 断言。
2.3 使用的大模型
配置文件：`.env`
MIDSCENE_MODEL_BASE_URL="https://conanaiplatform.zhenguanyu.com/litellm/"
MIDSCENE_MODEL_API_KEY="sk*"
MIDSCENE_MODEL_NAME="qwen3vlflash"
MIDSCENE_MODEL_FAMILY="qwen3vl"
使用公司内部LiteLLM 网关统一代理
当前主用Qwen3VLFlash（视觉多模态模型）
截图缩小到 30%（`screenshotResizeScale: 0.3`），降低 token 成本并提高响应速度
三、项目目录结构
AI_AUTO_TEST/
├── README.md 快速上手指南
├── .env 大模型网关/Key/模型名配置
│
├── IntoApp.yaml 「进入 App」前置流程
├── ShanDiantest.yaml 【测试环境】闪电 AI 回归测试主脚本
├── ShanDian.yaml 【线上环境】闪电 AI 回归测试主脚本
├── test.yaml 小流程验证用
├── scripts/ 编排脚本
│ ├── run_yaml_then_report_then_email.sh 【核心】一键编排
│ ├── run_yaml_by_task_name.py 按 tasks[].name 子集跑
│ ├── generate_midscene_email_report.py 生成 HTML 简报
│ └── send_midscene_report_email.py 发邮件
│
└── midscene_run/ Midscene 运行时产物
├── cache/ 视觉定位缓存
├── output/ summary*.json + 断言明细
├── report/ Midscene 原生完整 HTML 报告
├── log/ 细分日志
└── latesttestreport.html 【发送邮件 HTML 简报】
四、缓存机制详解
4.1 缓存的作用
⚡加速二次运行：首次运行后，后续运行直接使用缓存的定位方案
💰降低成本：减少大模型调用次数
📊提高稳定性：避免模型理解偏差导致的抖动
4.2 缓存配置
在 YAML 顶部配置：
yaml
agent:
cache:
id: "shandiantestcache"
strategy: "readwrite"
单个指令控制：
yaml
aiTap: 顶部的搜索框
cacheable: false 不使用缓存，每次都调用大模型
4.3 缓存文件
缓存存储在 `midscene_run/cache/*.cache.yaml`，格式示例：
yaml
step: 1
instruction: "顶部的搜索框"
result:
x: 360
y: 120
建议：
✅ 固定 UI 元素使用缓存（如顶栏按钮）
❌ 动态内容不使用缓存（如弹窗、活动提示）
五、测试用例编写指南
5.1 YAML 脚本结构
yaml
android:
deviceId: emulator5554 设备 ID
launch: com.fenbi.android.pedia App 包名
screenshotResizeScale: 0.3 截图缩小到 30%
agent:
cache:
id: "testcache"
strategy: "readwrite"
tasks:
name: 任务名称
continueOnError: false 失败是否继续
flow:
aiTap: 顶部的搜索框
aiInput: 今天天气怎么样
aiKeyboardPress: Enter
aiWaitFor: 页面加载完成，显示回复内容
timeout: 15000
aiAssert: 回复内容包含天气信息
5.2 典型场景示例
场景 1：处理弹窗
yaml
name: 首页可选关闭遮挡弹窗
continueOnError: false
flow:
ai: 若在屏幕下面有弹窗，若仅有右上角小「X」,点击「X」。若当前没有遮挡弹窗，不要点击。
cacheable: false
场景 2：权限申请
yaml
name: 录音可选允许弹窗
flow:
ai: 先根据当前截图判断是否出现系统权限类弹窗。仅当确实存在此类弹窗且上面有「允许」「同意」等按钮时，再点击；若没有权限弹窗，则不要执行任何点击。
cacheable: false
场景 3：滚动查找
yaml
name: 向下滑动寻找目标
flow:
aiScroll:
direction: down
distance: medium
aiWaitFor: 找到目标元素
5.3 按任务名筛选执行
使用 `run_yaml_by_task_name.py` 只运行指定任务：
bash
单个任务
python3 scripts/run_yaml_by_task_name.py ShanDian.yaml "断言录音弹窗"
多个任务（任一匹配即选中，按顺序执行）
python3 scripts/run_yaml_by_task_name.py ShanDian.yaml "录音 输入"
六、测试报告生成
6.1 Midscene 原生报告
位置：`midscene_run/report/midscenexxx.html`
完整的 HTML 报告（单文件几百 MB）
包含所有截图、日志、调用链
适合详细排查问题
6.2 精简 HTML 简报
位置：`midscene_run/latesttestreport.html`
由 `generate_midscene_email_report.py` 自动生成，包含：
报告内容：
📊 测试概览（通过率、耗时、模型信息）
✅ 断言明细表格（名称、结果、耗时）
❌ 失败原因分析（日志片段）
📝 最后执行步骤（便于定位中断位置）
七、邮件通知系统
如下截图:
数据来源：
`midscene_run/output/summary*.json` 测试概览
`midscene_run/output/<脚本><时间戳>.json` 断言明细
`midscene_run/log/yamlplayer.log` 执行流程
`midscene_run/log/aicall.log` AI 调用记录
手动生成报告：
python3 scripts/generate_midscene_email_report.py
手动发送邮件：
python3 scripts/send_midscene_report_email.py
八、一键编排脚本
8.1 核心脚本：run_yaml_then_report_then_email.sh
完整流程：
1. ✅ 进入 App（IntoApp.yaml）
2. ✅ 执行主测试（ShanDiantest.yaml）
3. ✅ 生成测试报告
4. ✅ 发送邮件通知
用法：
bash
基础用法（使用默认配置）
./scripts/run_yaml_then_report_then_email.sh
指定测试脚本
./scripts/run_yaml_then_report_then_email.sh ShanDiantest.yaml
跳过「进入 App」步骤（调试用）
SKIP_INTO_APP=1 ./scripts/run_yaml_then_report_then_email.sh ShanDiantest.yaml
8.2 Jenkins 集成
在 Jenkins 中创建 Shell 构建步骤：
bash
!/bin/bash
cd /path/to/AI_AUTO_TEST
设置环境变量
export MIDSCENE_CMD="npx midscene"
执行测试
./scripts/run_yaml_then_report_then_email.sh ShanDiantest.yaml
九、日志系统
9.1 日志文件分类
| 日志文件 | 内容 | 用途 |
| `yamlplayer.log` | 执行流程日志 | 定位最后执行步骤、查看任务顺序 |
| `aicall.log` | AI 调用日志 | 查看模型调用次数、token 消耗 |
| 其他日志 | 细分日志（agent、debug 等） | 深度调试 |
9.2 查看最后执行步骤
当测试中断时，查看 `yamlplayer.log` 最后的 `playing step` 日志：
playing step 12, flowItem={"aiTap": "底部右侧的键盘切换图标"}
这帮助快速定位中断位置。
9.3 AI 调用统计
查看 `aicall.log` 统计大模型调用次数和 token 消耗，优化测试脚本。
十、环境配置
10.1 依赖安装
Node.js 环境：
bash
npm install @midscene/cli
npm install @midscene/android
Python 环境：
bash
pip install pyyaml
Android 工具：
安装 ADB
安装 Android SDK
10.2 设备配置
Android 模拟器：
bash
启动模拟器
emulator avd <模拟器名称>
查看设备 ID
adb devices
在 YAML 中配置
android:
deviceId: emulator5554
真机连接：
bash
启用 USB 调试
连接设备后查看 ID
adb devices
配置设备 ID
android:
deviceId: <真机ID>
10.3 模型配置
编辑 `.env` 文件：
bash
MIDSCENE_MODEL_BASE_URL="https://conanaiplatform.zhenguanyu.com/litellm/"
MIDSCENE_MODEL_API_KEY="skyourapikey"
MIDSCENE_MODEL_NAME="qwen3vlflash"
MIDSCENE_MODEL_FAMILY="qwen3vl"
切换模型（如 Doubao Seed）：
bash
注释当前模型，取消注释目标模型
MIDSCENE_MODEL_NAME="qwen3vlflash"
MIDSCENE_MODEL_NAME="doubaoseed2.0pro260215"
MIDSCENE_MODEL_FAMILY="doubaoseed"
十一、最佳实践
11.1 测试用例编写建议
✅合理使用缓存
固定 UI 元素（如顶栏按钮）使用缓存
动态内容（如弹窗）设置 `cacheable: false`
✅错误容忍策略
弹窗处理设置 `continueOnError: false`
关键流程失败应立即停止
✅自然语言描述技巧
描述清晰具体：「顶部当前可见的返回按钮」比「返回按钮」更准确
包含条件判断：「若有弹窗则点击，没有则不操作」
11.2 性能优化
⚡截图缩放
yaml
screenshotResizeScale: 0.3 降低到 30%，加快响应速度
⚡减少不必要的 AI 调用
使用 `sleep` 代替简单等待
固定延迟用 `runAdbShell` 直接执行 ADB 命令
⚡缓存策略优化
首次运行后检查缓存命中率
调整 `cacheable` 配置
11.3 稳定性提升
🛡️弹窗处理
多次重复处理弹窗（避免遗漏）
使用条件判断（「若有则点击，没有则不操作」）
🛡️超时时间设置
yaml
aiWaitFor: 页面加载完成
timeout: 15000 根据实际情况调整
🛡️分段验证
将长流程拆分为多个 task
每个 task 添加明确的 `name`
十二、常见问题
12.1 Midscene 相关
Q: 元素定位失败怎么办？
检查自然语言描述是否准确
查看当前截图，确认元素可见
尝试设置 `cacheable: false` 重新识别
Q: AI 理解错误？
优化自然语言描述，添加更多上下文
检查截图是否清晰（缩放比例是否合适）
考虑切换模型（Qwen3VL ↔ Doubao Seed）
Q: 超时问题？
增加 `timeout` 时间
检查网络连接
确认设备性能正常
12.2 设备相关
Q: ADB 连接失败？
bash
重启 ADB 服务
adb killserver
adb startserver
检查设备连接
adb devices
Q: App 启动失败？
确认包名正确
检查 App 是否已安装
查看设备存储空间
12.3 报告与邮件
Q: 报告生成失败？
检查 `midscene_run/output/` 目录下是否有 `summary*.json`
查看 Python 脚本执行日志
Q: 邮件发送失败（535 authentication failed）？
确认使用的是「客户端专用密码」，不是网页登录密码
检查企业邮箱是否开启了 SMTP 功能
等待几分钟后重试（可能是服务器繁忙）
Q: 附件过大发送失败？
设置 `ATTACH_MIDSCENE_REPORT = False` 不发送附件
只发送精简 HTML 简报
附录
A. 常用命令速查
bash
安装依赖
npm install @midscene/android savedev
pip install pyyaml
运行测试
midscene ShanDiantest.yaml
按任务名筛选
python3 scripts/run_yaml_by_task_name.py ShanDian.yaml "录音"
一键执行
./scripts/run_yaml_then_report_then_email.sh
生成报告
python3 scripts/generate_midscene_email_report.py
发送邮件
python3 scripts/send_midscene_report_email.py
查看设备
adb devices
重启 ADB
adb killserver && adb startserver
B. 相关链接
Midscene 官方文档：https://midscenejs.com/
测试用例集：https://capas.zhenguanyu.com//cases/edit/19177
项目路径：`/Users/kanyun/.jenkins/workspace/自动化测试/AI_AUTO_TEST`
UI自动化需要配置的环境
一、android 运行环境
# 1. nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 2. Node.js
nvm install 25.8.0 && nvm use 25.8.0
# 3. Midscene（全局）
npm install -g @midscene/android
# 4. Python 环境&依赖
|
标准库
|
用途
|
|
smtplib / ssl
|
发邮件（SMTP）
|
|
json
|
解析 summary/断言 JSON
|
|
re
|
正则解析日志时间戳、<errors> 标签
|
|
calendar
|
时间戳换算（兼容 Python 3.6）
|
|
pathlib
|
文件路径操作
|
|
sys / os
|
系统输出、文件替换
|
|
email / mime
|
构造邮件 MIME 结构
|
# 5. ADB / Android SDK
adb devices # 验证设备可见
闪电 AI 远程执行自动化操作说明
一、适用场景
本文档用于说明如何通过远程服务器执行闪电 AI 自动化测试任务。执行过程中需要将本地手机通过 USB 连接到个人电脑，并通过 adb tcpip 将手机调试端口暴露给远程服务器使用。
二、前提条件
在开始操作前，请确认已满足以下条件：
1. 本地电脑已安装 adb 命令
⦁可通过以下命令检查：
adb version
2. 手机需要全程通过 USB 数据线连接电脑
⦁连接后，手机上如弹出「是否允许 USB 调试」或「是否允许访问」提示，请选择允许。
3. 执行脚本时，手机要有线上百科app，也要登陆成功
此脚本目前没有自动安装包、登陆操作，需要前置这些条件。
三、登录远程服务器
在本地终端执行：
ssh ape@10.1.6.50
密码：1020
四、进入自动化项目目录
登录远程服务器后，进入自动化测试目录：
cd /Users/ape/Documents/AUTO_TEST
项目代码目录为：
/Users/ape/Documents/AUTO_TEST/shan-dian-ai
五、获取手机 IP 地址
在手机上查看当前连接的 Wi-Fi 网络，例如：
kanyun
进入网络详情页，找到手机的 IP 地址。
示例：
10.1.24.252
注意：后续命令中的 IP 地址需要替换为你手机实际显示的 IP。
六、本地电脑开启 adb TCP 调试端口
在本地电脑执行以下命令：
adb tcpip 5555
执行过程中，手机可能会弹出「是否允许 USB 调试」或「是否允许访问」提示，请选择允许。
该命令的作用是让手机通过 5555 端口提供 adb 调试能力，方便远程服务器连接手机。
七、远程服务器连接手机
在远程服务器上执行：
adb connect 10.1.24.252:5555
其中 10.1.24.252 需要替换为你的手机 IP。
然后检查设备连接状态：
adb devices
如果连接成功，会看到类似输出：
List of devices attached
10.1.24.252:5555 device
如果状态不是 device ，请检查：
⦁手机是否仍连接 USB
⦁手机是否允许了 USB 调试
⦁手机和远程服务器网络是否互通
⦁IP 地址是否填写正确
⦁adb 服务是否正常
八、测试账号
线上测试账号：
10093582442
九、执行自动化脚本
进入项目目录：
cd /Users/ape/Documents/AUTO_TEST/shan-dian-ai
执行自动化脚本：
sh ./scripts/run_and_email.sh ShanDian.yaml your_mail@qq.com
其中：
⦁ ShanDian.yaml ：自动化用例配置文件
⦁ your_mail@qq.com ：测试结果接收邮箱，请替换为自己的邮箱地址
示例：
sh ./scripts/run_and_email.sh ShanDian.yaml zhangdanbj03@kanyun.com
十、常见问题排查
1. 执行 adb devices 看不到设备
可以尝试：
adb kill-server
adb start-server
adb devices
如果仍然看不到设备，请重新插拔 USB 数据线，并确认手机已开启 USB 调试。
2. adb connect 失败
请检查：
1. 手机 IP 是否正确；
2. 手机和远程服务器是否在同一网络或网络可达；
3. 是否已在本地电脑执行：
adb tcpip 5555
4. 手机是否弹出授权提示且已点击允许。
3. 执行自动化时提示找不到设备
在远程服务器上重新执行：
adb devices
确认设备状态为：
device
如果不是，请重新执行：
adb connect 手机IP:5555
4. 自动化脚本执行失败
建议按以下顺序排查：
1. 确认当前目录是否正确：
pwd
2. 确认 YAML 文件是否存在：
ls ShanDian.yaml
3. 确认设备连接正常：
adb devices
4. 查看脚本报错日志，根据具体错误继续定位。
十一、完整操作流程汇总
# 1. 登录远程服务器
ssh ape@10.1.6.50
# 2. 进入项目目录
cd /Users/ape/Documents/AUTO_TEST/shan-dian-ai
# 3. 本地电脑开启 adb tcpip 模式
adb tcpip 5555
# 4. 远程服务器连接手机
adb connect 10.1.24.252:5555
# 5. 检查设备状态
adb devices
# 6. 执行自动化脚本
sh ./scripts/run_and_email.sh ShanDian.yaml your_mail@qq.com
十二、目录结构说明
文件
IntoApp.yaml 进入百科app的流程
ShanDian.yaml 执行闪电AI的流程
目录
midscene_run 执行中的日志、报告
错位定位
查看报告最直观，报告都是html 格式
报告位置：midscene_run/report
服务器无法看html , 可以下载到本地看，在本地执行命令如下：
scp ape@10.1.6.50:/Users/ape/Documents/AUTO_TEST/shan-dian-ai/midscene_run/report/ShanDian-2026-07-17_16-47-46-40d9885d.html /Users/kanyun/Desktop
十二、修改闪电 AI 自动化代码
代码地址：https://gitlab-ee.zhenguanyu.com/zhangdanbj03/shan-dian-ai
分支地址：https://gitlab-ee.zhenguanyu.com/autotest/shan-dian-ai/-/tree/feature/zd-test?ref_type=heads
修改完成后，在服务器拉取一下就可以执行新代码
cd /Users/ape/Documents/AUTO_TEST
git clone https://gitlab-ee.zhenguanyu.com/zhangdanbj03/shan-dian-ai.git
git pull
浙公网安备 33010602011771号