# AppPerformanceTesting

**Repository Path**: xiaobai_long/AppPerformanceTesting

## Basic Information

- **Project Name**: AppPerformanceTesting
- **Description**: APP性能测试
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-12-17
- **Last Updated**: 2025-12-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# APP性能测试框架

一个全面的Android APP性能测试框架，支持启动性能、内存、网络、电池、UI渲染等全方位的性能测试和监控。

## 📋 目录

- [快速参考](#快速参考)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [测试类型](#测试类型)
- [测试策略优化](#测试策略优化)
- [使用示例](#使用示例)
- [报告说明](#报告说明)
- [报告优化版本对比](#报告优化版本对比)
- [最佳实践](#最佳实践)
- [使用场景示例](#使用场景示例)
- [代码质量](#代码质量)
- [错误处理](#错误处理)
- [单元测试](#单元测试)
- [常见问题](#常见问题)
- [技术支持](#技术支持)
- [已知限制](#已知限制)
- [更新日志](#更新日志)

## ✨ 功能特性

### 核心功能

- **启动性能测试**：冷启动、热启动时间测试
- **内存测试**：内存增长、内存泄漏检测
- **网络性能测试**：网络响应时间、流量监控
- **电池测试**：后台耗电、活跃使用耗电测试
- **UI渲染测试**：FPS测试、滚动性能测试
- **综合性能监控**：实时监控CPU、内存、网络、电池等多项指标
- **Monkey随机测试**：支持随机事件注入，压力测试和稳定性测试

### 性能指标

#### CPU指标
- CPU使用率（平均、峰值）
- CPU用户态使用率
- CPU系统态使用率
- CPU IO等待

#### 内存指标
- 内存PSS（Proportional Set Size）
- 内存RSS（Resident Set Size）
- Java堆内存
- Native堆内存
- 图形内存

#### 网络指标
- 网络接收流量（总量、平均值）
- 网络发送流量（总量、平均值）
- 网络请求响应时间
- 网络成功率

#### 电池指标
- 电池电量消耗
- 电池温度
- 电池电压
- 电流消耗

#### 图形渲染指标
- FPS（帧率）
- 卡顿帧数
- 平均帧时间
- P95帧时间

#### 系统资源指标
- **线程统计**：
  - 线程总数（平均值、峰值）
  - 线程分类统计（按名称分类、按状态分类）
  - 按名称分类：主线程、UI线程、网络线程、数据库线程、后台线程、异步线程、Native线程、GC线程、其他线程
  - 按状态分类：运行中、睡眠、等待、僵尸、其他状态
- 文件描述符数量
- 磁盘读取/写入

### 报告功能

- **HTML可视化报告**：包含图表、表格、状态指示
- **执行摘要**：一页关键指标总览，综合评分（0-100分）
- **性能评分系统**：各项性能自动评分（启动、内存、FPS、网络、电池）
- **问题优先级分类**：自动分类问题（CRITICAL/HIGH/MEDIUM/LOW）
- **问题诊断与建议**：智能分析问题原因，提供优化建议
- **时间序列图表**：交互式Chart.js图表展示性能趋势
- **历史对比分析**：与上次测试对比，显示性能变化
- **趋势分析**：最近30天的性能趋势分析
- **PDF/Excel导出**：支持导出PDF和Excel格式报告
- **CSV数据导出**：原始性能数据
- **中英文双语**：报告支持中英文显示
- **状态标识**：自动标记正常/警告/异常状态

### 测试策略优化

- **分层测试策略**：快速测试（5-10分钟）、标准测试（15-30分钟）、深度测试（1-2小时）
- **智能测试选择**：根据Git代码变更自动选择测试类型
- **性能基线管理**：自动保存基线，检测性能退化
- **快速测试模式**：优化配置，缩短测试时间
- **测试跳过机制**：根据策略自动跳过耗时测试

### 代码质量特性

- **完整的类型提示**：所有核心方法都有类型注解
- **详细的文档字符串**：遵循Google风格的docstrings
- **输入验证**：所有公共方法都有参数验证
- **统一异常处理**：用户友好的错误消息和解决建议
- **重试机制**：自动重试失败的ADB命令和操作
- **错误恢复**：智能的错误恢复策略
- **单元测试**：核心功能都有单元测试覆盖
- **模块化设计**：功能拆分到专门的文件，便于维护

## 📁 项目结构

```
AppPerformanceTesting/
├── config/                    # 配置文件目录
│   ├── test_config.yaml      # 主配置文件
│   ├── devices.yaml          # 设备配置文件
│   ├── config_loader.py      # 配置加载器
│   └── environments/         # 环境配置
├── core/                      # 核心模块
│   ├── device_manager.py     # 设备管理器（ADB交互）
│   ├── performance_monitor.py # 性能监控器
│   ├── report_generator.py   # 报告生成器
│   ├── report_enhancer.py    # 报告增强模块（执行摘要、评分、诊断）
│   ├── report_exporter.py    # 报告导出模块（PDF/Excel）
│   ├── history_manager.py    # 历史数据管理（对比、趋势分析）
│   ├── test_runner.py        # 测试运行器（各类测试执行逻辑）
│   ├── test_strategy.py      # 测试策略管理（分层测试、智能选择）
│   ├── exceptions.py         # 自定义异常类
│   ├── validators.py         # 输入验证工具
│   ├── retry.py              # 重试机制
│   └── error_recovery.py     # 错误恢复机制
├── tests/                     # 测试用例
│   ├── test_launch_performance.py  # 启动性能测试
│   ├── test_memory_leak.py         # 内存测试
│   ├── test_network_performance.py # 网络测试
│   ├── test_battery_consumption.py # 电池测试
│   ├── test_ui_rendering.py         # UI渲染测试
│   ├── test_device_manager.py      # 设备管理器单元测试
│   ├── test_validators.py           # 验证器单元测试
│   ├── test_retry.py                # 重试机制单元测试
│   └── conftest.py                   # pytest配置
├── utils/                     # 工具类
│   ├── user_operations.py    # 用户操作封装
│   ├── monkey_test.py        # Monkey随机测试模块
│   ├── adb_utils.py          # ADB工具函数
│   ├── logging_setup.py      # 日志配置模块
│   ├── environment_collector.py # 测试环境信息收集
│   ├── screenshot_analyzer.py # 截图分析工具
│   └── data_processor.py     # 数据处理工具
├── config/                    # 配置文件
│   ├── test_config.yaml      # 主配置文件
│   ├── quick_test_config.yaml # 快速测试配置
│   └── ...
├── docs/                      # 文档目录
│   ├── TEST_STRATEGY_GUIDE.md # 测试策略使用指南
│   └── ...
├── reports/                   # 测试报告输出目录
├── screenshots/               # 截图保存目录
├── recordings/                # 录屏保存目录
├── logs/                      # 日志目录
├── results/                   # 测试结果目录
├── run_tests.py              # 测试运行器入口（主程序）
├── requirements.txt          # Python依赖
└── README.md                 # 项目说明
```

## ⚡ 快速参考

### 常用命令速查

```bash
# 快速测试（5-10分钟）
python run_tests.py --strategy quick --test-type all

# 标准测试（15-30分钟）
python run_tests.py --strategy standard --test-type all

# 智能测试选择
python run_tests.py --smart-select --strategy quick

# 性能基线检查
python run_tests.py --baseline-check --strategy standard

# 查看可用设备
python run_tests.py --list-devices

# 运行特定测试
python run_tests.py --test-type launch --device-id YOUR_DEVICE_ID
```

### 测试策略对比

| 策略 | 命令 | 时长 | 适用场景 |
|------|------|------|---------|
| Quick | `--strategy quick` | 5-10分钟 | 日常开发、CI/CD |
| Standard | `--strategy standard` | 15-30分钟 | 版本发布前 |
| Deep | `--strategy deep` | 1-2小时 | 深度分析 |

## 🚀 快速开始

### 1. 环境要求

- Python 3.8+
- Android SDK (ADB工具)
- Android设备或模拟器（已开启USB调试）

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置设备

编辑 `config/test_config.yaml`，配置你的APP信息：

```yaml
app:
  package_name: "com.example.app"  # 你的APP包名
  main_activity: "com.example.app.MainActivity"  # 启动Activity
  app_name: "测试APP"
  app_version: "1.0.0"

device:
  device_id: "AERFUT4628001125"  # 设备ID（可通过 adb devices 查看）
  platform: "android"
  platform_version: "13.0"
```

### 4. 运行测试

#### 基础用法

```bash
# 运行所有测试（标准策略，15-30分钟）
python run_tests.py --test-type all --device-id YOUR_DEVICE_ID

# 运行特定测试
python run_tests.py --test-type launch --device-id YOUR_DEVICE_ID
python run_tests.py --test-type memory --device-id YOUR_DEVICE_ID
python run_tests.py --test-type network --device-id YOUR_DEVICE_ID
python run_tests.py --test-type battery --device-id YOUR_DEVICE_ID
python run_tests.py --test-type ui --device-id YOUR_DEVICE_ID
python run_tests.py --test-type monitor --device-id YOUR_DEVICE_ID
```

#### 测试策略（推荐）

```bash
# 快速测试（5-10分钟）- 日常开发使用
python run_tests.py --strategy quick --test-type all

# 标准测试（15-30分钟）- 版本发布前使用
python run_tests.py --strategy standard --test-type all

# 深度测试（1-2小时）- 深度性能分析
python run_tests.py --strategy deep --test-type all

# 智能测试选择（根据Git变更自动选择测试）
python run_tests.py --smart-select --strategy quick

# 性能基线检查（检测性能退化）
python run_tests.py --baseline-check --strategy standard
```

#### 其他选项

```bash
# 列出可用设备
python run_tests.py --list-devices

# 使用自定义配置
python run_tests.py --config my_config.yaml --strategy custom
```

## ⚙️ 配置说明

### 主配置文件 (`config/test_config.yaml`)

#### 应用配置
```yaml
app:
  package_name: "com.example.app"
  main_activity: "com.example.app.MainActivity"
  app_name: "测试APP"
  app_version: "1.0.0"
```

#### 性能测试参数
```yaml
performance:
  launch_test:
    cold_launch_iterations: 10      # 冷启动测试次数
    warm_launch_iterations: 10      # 热启动测试次数
    launch_time_threshold_ms: 2000  # 启动时间阈值（毫秒）
  
  memory_test:
    operation_cycles: 10            # 操作循环次数
    memory_growth_threshold_mb: 20  # 内存增长阈值（MB）
  
  monitoring:
    sampling_interval_sec: 1.0      # 采样间隔（秒）
    monitoring_duration_sec: 300    # 监控时长（秒）
```

#### Monkey随机测试配置
```yaml
performance:
  monkey_test:
    enabled: true                   # 是否启用Monkey测试
    event_count: 5000               # 随机事件数量
    throttle_ms: 300                # 事件间隔（毫秒）
    seed: null                      # 随机种子（null为随机，固定值可复现）
    ignore_crashes: true            # 忽略崩溃继续执行
    ignore_timeouts: true           # 忽略超时继续执行
    ignore_security_exceptions: true # 忽略安全异常
    # 事件类型比例（百分比）
    pct_touch: 40                   # 触摸事件
    pct_motion: 15                  # 动作事件（滑动等）
    pct_syskeys: 5                  # 系统按键事件
    pct_appswitch: 5                # 应用切换事件
    pct_anyevent: 35                # 其他事件
```

#### 日志配置
```yaml
logging:
  level: "INFO"                     # 日志级别
  file_enabled: true                # 是否启用文件日志
  file_path: "./logs/performance_tests.log"
  rotation_type: "daily"            # 轮转方式：daily（按天）或 size（按大小）
  max_file_size_mb: 10              # 按大小轮转时的最大文件大小（MB）
  backup_count: 30                  # 保留的日志文件数量（按天轮转时为保留天数）
  console_enabled: true             # 是否启用控制台日志
```

## 🧪 测试类型

### 1. 启动性能测试 (`launch`)

测试应用的冷启动和热启动时间。

**测试指标：**
- 冷启动时间（平均、中位数、P95、P99）
- 热启动时间（平均、中位数、P95、P99）
- 所有启动时间记录

**示例：**
```bash
python run_tests.py --test-type launch --device-id YOUR_DEVICE_ID
```

### 2. 内存测试 (`memory`)

检测应用在多次操作后的内存增长情况。

**测试指标：**
- 初始内存
- 操作后内存
- 内存增长量
- 内存泄漏检测

**示例：**
```bash
python run_tests.py --test-type memory --device-id YOUR_DEVICE_ID
```

### 3. 网络性能测试 (`network`)

测试应用的网络请求性能。

**测试指标：**
- 网络响应时间
- 网络流量（接收/发送）
- 请求成功率
- 慢请求统计

**示例：**
```bash
python run_tests.py --test-type network --device-id YOUR_DEVICE_ID
```

### 4. 电池测试 (`battery`)

测试应用的后台和活跃使用时的电池消耗。

**测试指标：**
- 后台耗电（每小时）
- 活跃使用耗电（每小时）
- 电池温度
- 电流消耗

**示例：**
```bash
python run_tests.py --test-type battery --device-id YOUR_DEVICE_ID
```

### 5. UI渲染测试 (`ui`)

测试应用的UI渲染性能。

**测试指标：**
- FPS（帧率）
- 滚动性能
- 卡顿帧数
- 帧时间

**示例：**
```bash
python run_tests.py --test-type ui --device-id YOUR_DEVICE_ID
```

### 6. 综合性能监控 (`monitor`)

实时监控应用的多项性能指标。

**监控指标：**
- CPU使用率（平均、峰值、用户态、系统态）
- 内存使用（PSS、RSS、堆内存）
- 网络流量（接收、发送）
- 电池状态（电量、温度、电压、电流）
- FPS和卡顿
- 磁盘IO
- **线程统计和分类**：
  - 线程总数（平均值、峰值）
  - 按名称分类：主线程、UI线程、网络线程、数据库线程、后台线程、异步线程、Native线程、GC线程、其他线程
  - 按状态分类：运行中、睡眠、等待、僵尸、其他状态
  - 各类线程的数量和占比
- 文件描述符数量

**示例：**
```bash
python run_tests.py --test-type monitor --device-id YOUR_DEVICE_ID
```

### 7. Monkey随机测试

Monkey测试通过配置文件中 `performance.monkey_test.enabled: true` 启用，会在以下场景自动执行：

- **内存测试**：在常规内存测试后执行Monkey压力测试，检测随机操作下的内存泄漏
- **综合监控**：在用户操作流程后执行Monkey测试，模拟真实用户随机操作

**Monkey测试特点：**
- 自动注入随机触摸、滑动、按键等事件
- 可配置事件数量和间隔
- 支持设置随机种子以复现测试
- 自动统计崩溃和ANR次数
- 内存测试后自动清除APP缓存，不影响后续测试

**测试结果：**
- `events_injected`：注入的事件数量
- `crashes`：检测到的崩溃次数
- `anr`：检测到的ANR次数
- `memory_growth_mb`：内存变化（仅内存压力测试）

**线程分类说明：**

线程分类功能可以帮助你：
- 了解应用的线程使用情况
- 识别线程泄漏问题（线程数量异常增长）
- 分析线程类型分布（是否创建了过多不必要的线程）
- 监控线程状态分布（是否有大量线程处于等待状态）
- 优化线程管理策略

## 📊 使用示例

### 测试APP（需要用户操作）

对于需要用户认证和填写资料的APP，框架提供了专用的用户操作流程：

1. **配置应用信息**
```yaml
app:
  package_name: "com.example.loanapp"
  main_activity: "com.example.loanapp.MainActivity"
```

2. **自定义操作流程**

编辑 `utils/user_operations.py` 中的 `get_loan_app_operations()` 方法，根据实际APP调整操作坐标：

```python
def get_loan_app_operations(self):
    return [
        ("点击登录按钮", "shell input tap 977 2350"),
        ("输入手机号", "input_text:0912345678"),  # 使用安全的文本输入
        # ... 更多操作
    ]
```

3. **运行测试**
```bash
python run_tests.py --test-type monitor --device-id YOUR_DEVICE_ID
```

框架会自动：
- 启动应用
- 等待应用完全加载
- 验证应用运行状态
- 执行用户操作流程（登录、填写资料等）
- 监控性能指标
- 生成报告

## 📈 报告说明

### 报告位置

测试完成后，报告保存在 `reports/` 目录下，按时间戳命名：
```
reports/
└── full_report_20251217_103804/
    ├── index.html              # 主报告（HTML，包含所有优化功能）
    ├── performance_report.xlsx # Excel报告（多工作表）
    ├── performance_report.pdf  # PDF报告
    ├── summary.txt             # 文本摘要
    ├── test_results.json       # 测试结果（JSON）
    ├── test_config.json        # 测试配置
    ├── performance_report.html # 综合监控报告
    ├── performance_charts.png  # 性能图表
    └── performance_data.csv    # 性能数据（CSV）
```

### 报告优化功能（v2.0）

#### 1. 执行摘要（Executive Summary）

报告开头提供一页关键指标总览：

- **综合评分**：0-100分，快速判断整体性能水平
  - 80-100分：优秀（绿色）
  - 60-79分：良好（黄色）
  - 40-59分：一般（橙色）
  - 0-39分：较差（红色）

- **各项性能评分**：
  - 启动性能评分（冷启动60分 + 热启动40分）
  - 内存性能评分（增长50分 + PSS 50分）
  - 渲染性能评分（平均FPS 60分 + 最低FPS 40分）
  - 网络性能评分（平均延迟60分 + P95延迟40分）
  - 电池性能评分（0-100分）

- **问题统计**：按优先级分类显示问题数量
  - CRITICAL：严重问题（红色）
  - HIGH：重要问题（橙色）
  - MEDIUM：一般问题（黄色）
  - LOW：轻微问题（蓝色）

#### 2. 问题诊断与建议

每个问题自动提供：

- **问题诊断**：智能分析问题原因
  - 启动时间超标 → 分析可能原因（初始化代码过多、主线程阻塞等）
  - 内存使用超标 → 分析可能原因（内存泄漏、缓存未释放等）
  - FPS偏低 → 分析可能原因（UI渲染过重、主线程阻塞等）

- **优化建议**：针对每个问题提供3-5条具体建议
  - 根据优先级显示不同数量的建议
  - 标注优化难度和预期效果

#### 3. 时间序列图表

使用Chart.js生成交互式图表：

- **CPU使用率趋势图**：实时监控CPU使用情况
- **内存使用趋势图**：监控内存变化趋势
- **FPS趋势图**：监控帧率变化

图表支持：
- 缩放和交互
- 鼠标悬停显示详细数值
- 响应式设计

#### 4. 历史对比分析

- **与上次测试对比**：
  - 显示上次值和本次值
  - 计算变化量和变化率
  - 趋势图标（📈改善 / 📉退化）

- **性能趋势分析**（最近30天）：
  - 显示当前值、平均值、趋势方向
  - 数据点数量和数值范围
  - 自动计算趋势百分比

#### 5. 测试环境信息

完整的测试环境信息展示：

- **测试主机信息**：OS、Python版本、主机名
- **设备信息**：设备ID、型号、Android版本、屏幕、内存、存储、电池
- **应用信息**：包名、版本、Activity
- **网络环境**：WiFi信号强度、网络类型、IP地址
- **系统状态**：CPU核心数、可用内存、运行进程数、系统负载

#### 6. PDF/Excel导出

- **Excel导出**：
  - 多个工作表（执行摘要、启动性能、内存测试、监控数据、问题列表）
  - 包含详细数据和统计信息
  - 便于数据分析和处理

- **PDF导出**：
  - 格式化的PDF报告
  - 包含配置信息、执行摘要、关键指标
  - 适合打印和分享

### 报告内容

#### HTML报告包含（优化后）：

1. **执行摘要** ⭐ 新增
   - 综合评分和状态
   - 各项性能评分卡片
   - 问题统计（按优先级）

2. **问题诊断与建议** ⭐ 新增
   - 按优先级排序的问题列表
   - 每个问题的诊断分析
   - 优化建议列表

3. **历史对比分析** ⭐ 新增
   - 与上次测试的对比表格
   - 性能趋势分析（最近30天）

4. **性能指标时间序列** ⭐ 新增
   - 交互式Chart.js图表
   - CPU、内存、FPS趋势图

5. **测试环境信息** ⭐ 新增
   - 完整的设备、应用、网络、系统信息

6. **测试结果表格**
   - 所有测试项的指标
   - 状态标识（✅ 正常 / ⚠️ 警告 / ❌ 异常）
   - 中英文双语显示

7. **综合监控报告**
   - 性能图表（时间序列）
   - 摘要统计表格
   - 详细指标表格
   - **线程统计和分类表格**：
     - 线程统计表格：显示总线程数
     - 按名称分类表格：显示各类线程的数量和占比
     - 按状态分类表格：显示各状态线程的数量和占比
   - CSV数据下载

8. **报告导出** ⭐ 新增
   - Excel导出按钮
   - PDF导出按钮

### 报告指标说明

- **CPU使用率**：应用占用的CPU百分比
- **内存PSS**：Proportional Set Size，按比例分配的内存
- **内存RSS**：Resident Set Size，实际占用的物理内存
- **网络接收/发送**：监控期间的网络流量增量
- **磁盘读取/写入**：监控期间的磁盘IO增量
- **卡顿帧数**：帧时间超过16.67ms的帧数
- **FPS**：每秒帧数，反映UI流畅度
- **线程统计**：进程中的线程总数
- **线程分类（按名称）**：
  - 主线程：应用主线程
  - UI线程：UI渲染相关线程（RenderThread、Choreographer等）
  - 网络线程：网络请求相关线程（OkHttp、Http、Volley、Retrofit等）
  - 数据库线程：数据库操作线程（SQLite、DB等）
  - 后台线程：后台任务线程（Background、Worker、ThreadPool等）
  - 异步线程：异步任务线程（AsyncTask、Async、Executor、Handler等）
  - Native线程：Native代码线程
  - GC线程：垃圾回收线程（GC、Finalizer、ReferenceQueue等）
  - 其他线程：未分类的线程
- **线程分类（按状态）**：
  - 运行中（Running）：正在执行的线程
  - 睡眠（Sleeping）：等待中的线程
  - 等待（Waiting）：等待资源的线程
  - 僵尸（Zombie）：已结束但未清理的线程
  - 其他：其他状态的线程

## 💻 代码质量

### 类型提示

框架的所有核心方法都包含完整的类型提示，提供更好的IDE支持和类型检查：

```python
def execute_adb(self, command: str, raise_on_error: bool = False) -> str:
    """
    执行ADB命令（带重试机制）
    
    Args:
        command: ADB命令（不包含 'adb -s device_id' 前缀）
        raise_on_error: 如果命令返回非零退出码是否抛出异常
        
    Returns:
        ADB命令的标准输出
        
    Raises:
        ValidationError: 如果命令为空
        DeviceOperationError: 如果命令执行失败且raise_on_error=True
    """
    pass
```

### 输入验证

所有公共方法都集成了输入验证，确保参数的有效性：

```python
from core.validators import validate_package_name, validate_positive

def start_app(self, package_name: str, timeout: int = 30) -> float:
    validate_package_name(package_name)  # 验证包名格式
    validate_positive(timeout, "timeout")  # 验证超时时间
    # ... 方法实现
```

### 文档字符串

所有公共方法都有详细的文档字符串，包括：
- 方法描述
- 参数说明
- 返回值说明
- 异常说明
- 使用示例（部分方法）

## 🛡️ 错误处理

### 统一异常处理

框架使用统一的异常处理机制，所有异常都提供：
- **用户友好的错误消息**：易于理解的错误描述
- **详细的技术信息**：包含错误的技术细节
- **解决建议**：提供具体的解决步骤
- **错误代码**：便于程序化处理

```python
from core.exceptions import DeviceConnectionError

try:
    device = AndroidDeviceManager("emulator-5554")
except DeviceConnectionError as e:
    print(e)  # 显示用户友好的消息和建议
    print(e.suggestions)  # 获取解决建议列表
    print(e.error_code)  # 获取错误代码
```

### 重试机制

框架内置了智能重试机制，自动处理临时性错误：

```python
@retry_on_failure(
    max_attempts=3,
    delay=1.0,
    backoff=2.0,
    exceptions=(DeviceOperationError,)
)
def execute_adb(self, command: str) -> str:
    # ADB命令会自动重试最多3次
    pass
```

**重试特性：**
- 指数退避策略（延迟时间逐渐增加）
- 可配置的重试次数和延迟
- 异常类型过滤（只重试指定异常）
- 错误消息过滤（只重试包含特定关键词的错误）

### 错误恢复机制

框架支持智能错误恢复，自动尝试修复常见问题：

```python
@with_recovery({
    AppLaunchError: [
        RecoveryAction.RESTART_APP,
        RecoveryAction.RETRY,
        RecoveryAction.FAIL
    ]
})
def start_app(self, package_name: str, activity_name: str) -> float:
    # 如果启动失败，会自动尝试重启应用
    pass
```

**支持的恢复操作：**
- `RETRY`: 重试操作
- `RESTART_ADB`: 重启ADB服务
- `RECONNECT_DEVICE`: 重新连接设备
- `RESTART_APP`: 重启应用
- `RESET_DEVICE_STATE`: 重置设备状态

### 错误消息示例

```
❌ 无法连接到Android设备
技术详情: ADB命令执行结果: error: device not found

建议解决方案：
  1. 检查设备是否已连接: adb devices
  2. 确保USB调试已启用
  3. 尝试重新连接USB线
  4. 如果是模拟器，检查模拟器是否正在运行
  5. 尝试重启ADB服务: adb kill-server && adb start-server

错误代码: DEVICE_CONNECTION_FAILED
```

## 🧪 单元测试

### 运行测试

框架包含完整的单元测试套件：

```bash
# 运行所有测试
pytest tests/

# 运行特定测试文件
pytest tests/test_device_manager.py -v

# 运行验证器测试
pytest tests/test_validators.py -v

# 运行重试机制测试
pytest tests/test_retry.py -v

# 显示覆盖率
pytest --cov=core --cov=utils tests/
```

### 测试覆盖

当前测试覆盖：
- ✅ 设备管理器核心功能
- ✅ 输入验证工具
- ✅ 重试机制
- ✅ 异常处理

### 测试示例

```python
def test_execute_adb_success(self, mock_device_id):
    """测试成功执行ADB命令"""
    with patch('core.device_manager.subprocess.run') as mock_subprocess:
        mock_subprocess.return_value = Mock(
            stdout="success output",
            stderr="",
            returncode=0
        )
        
        device = AndroidDeviceManager(mock_device_id)
        result = device.execute_adb("shell echo test")
        
        assert result == "success output"
```

## 💡 最佳实践

### 1. 测试策略选择

**日常开发阶段：**
- 使用 `--strategy quick` 进行快速验证
- 结合 `--smart-select` 只测试变更的功能
- 预估时间：5-10分钟

**测试阶段：**
- 使用 `--strategy standard` 进行完整测试
- 启用 `--baseline-check` 检测性能退化
- 预估时间：15-30分钟

**发布阶段：**
- 使用 `--strategy deep` 进行深度验证
- 确保所有测试通过后再发布
- 预估时间：1-2小时

### 2. 性能基线管理

**建立基线：**
```bash
# 在稳定版本上建立基线
python run_tests.py --baseline-check --strategy standard --test-type all
```

**定期检查：**
```bash
# 每次版本发布前检查性能退化
python run_tests.py --baseline-check --strategy standard --test-type all
```

**基线文件位置：** `reports/baseline.json`

### 3. 报告使用建议

**快速查看：**
1. 打开HTML报告，直接查看执行摘要
2. 查看综合评分，快速判断整体性能
3. 查看问题统计，了解问题严重程度

**详细分析：**
1. 查看问题诊断与建议，了解具体问题
2. 查看时间序列图表，分析性能趋势
3. 查看历史对比，了解性能变化

**报告分享：**
1. 导出PDF报告，便于打印和分享
2. 导出Excel报告，便于数据分析
3. 分享报告链接给团队成员

### 4. CI/CD集成

**GitHub Actions示例：**
```yaml
name: Performance Test

on:
  pull_request:
    paths:
      - 'app/**'

jobs:
  quick-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run quick performance test
        run: |
          python run_tests.py \
            --strategy quick \
            --smart-select \
            --baseline-check
```

### 5. 性能优化流程

1. **发现问题**：查看报告中的问题诊断
2. **分析原因**：根据诊断信息定位问题
3. **实施优化**：按照优化建议进行改进
4. **验证效果**：运行快速测试验证
5. **更新基线**：优化后更新性能基线

## 📚 使用场景示例

### 场景1：日常开发快速验证

```bash
# 快速测试，5-10分钟完成
python run_tests.py --strategy quick --test-type launch,memory

# 智能选择，只测试变更的功能
python run_tests.py --smart-select --strategy quick
```

**适用场景：**
- 代码提交前快速验证
- CI/CD流水线中的快速检查
- 日常开发中的性能回归

### 场景2：版本发布前完整测试

```bash
# 标准测试，15-30分钟
python run_tests.py --strategy standard --test-type all

# 带性能基线检查
python run_tests.py --strategy standard --test-type all --baseline-check
```

**适用场景：**
- 版本发布前的完整验证
- 定期性能回归测试
- 功能验证后的性能检查

### 场景3：深度性能分析

```bash
# 深度测试，1-2小时
python run_tests.py --strategy deep --test-type all
```

**适用场景：**
- 性能瓶颈分析
- 长时间稳定性测试
- 深度性能优化

### 场景4：性能退化检测

```bash
# 首次运行建立基线
python run_tests.py --baseline-check --strategy standard --test-type all

# 后续运行自动对比
python run_tests.py --baseline-check --strategy standard --test-type all
```

**输出示例：**
```
📊 性能基线对比...
   ⚠️  检测到性能退化:
      📉 cold_launch_avg: 1200.00 → 1800.00 (50.0%)
      📈 memory_pss_avg: 200.00 → 180.00 (-10.0%)
   📝 基线已更新
```

## ❓ 常见问题

### Q1: CPU使用率、网络流量等指标显示为0

**原因：**
- 应用可能还未完全启动
- 应用没有实际运行（进程不存在）
- 没有执行会触发网络请求的操作

**解决方案：**
1. 确保应用真正在前台运行
2. 执行会触发网络请求的用户操作
3. 检查日志文件 `logs/performance_tests.log` 查看详细信息
4. 增加等待时间，让应用完全加载

### Q2: 如何获取UI元素的坐标？

**方法1：使用UI Automator**
```bash
adb shell uiautomator dump /sdcard/ui.xml
adb pull /sdcard/ui.xml .
# 查看ui.xml文件，找到元素的bounds属性
```

**方法2：使用开发者选项**
1. 在手机上开启"指针位置"（开发者选项）
2. 点击UI元素，查看屏幕上的坐标
3. 记录坐标并更新到操作流程中

### Q3: 输入文本时前导0丢失

**解决方案：**
使用 `input_text:` 前缀而不是 `shell input text`：
```python
("输入手机号", "input_text:0912345678")  # ✅ 正确
("输入手机号", "shell input text 0912345678")  # ❌ 会丢失前导0
```

### Q4: 设备连接失败

**解决方案：**
1. 确保设备已通过USB连接
2. 确保已开启USB调试模式
3. 运行 `adb devices` 检查设备是否识别
4. 使用 `--list-devices` 查看可用设备

### Q5: 如何查看日志？

日志文件保存在 `logs/performance_tests.log`，包含：
- 测试执行过程
- 错误信息
- 性能数据采集详情

### Q6: 线程统计和分类功能如何使用？

**功能说明：**
- 线程统计功能会自动收集应用进程中的所有线程信息
- 按线程名称进行智能分类（主线程、UI线程、网络线程等）
- 按线程状态进行分类（运行中、睡眠、等待等）
- 在综合监控报告中显示线程统计和分类表格

**查看方式：**
1. 运行综合性能监控测试：`python run_tests.py --test-type monitor --device-id YOUR_DEVICE_ID`
2. 在生成的报告中查看"线程统计"部分
3. 查看"按名称分类"表格了解线程类型分布
4. 查看"按状态分类"表格了解线程状态分布

**应用场景：**
- 检测线程泄漏（线程数量异常增长）
- 分析线程使用情况（是否创建了过多不必要的线程）
- 优化线程管理策略
- 识别性能瓶颈（大量线程处于等待状态）

### Q7: 如何处理ADB命令失败？

**框架自动处理：**
- 框架内置了重试机制，ADB命令失败会自动重试（最多3次）
- 如果重试失败，会尝试错误恢复（如重启ADB服务）
- 所有错误都会提供友好的错误消息和解决建议

**手动处理：**
```python
try:
    result = device.execute_adb("shell echo test", raise_on_error=True)
except DeviceOperationError as e:
    print(e.user_friendly_message)  # 用户友好的错误消息
    print(e.suggestions)  # 解决建议列表
    # 根据错误代码进行特定处理
    if e.error_code == "ADB_TIMEOUT":
        # 处理超时错误
        pass
```

### Q8: 网络接收/发送或磁盘读写数据为0？

**网络数据为0的原因：**
- Android 9+ 移除了 `/proc/net/xt_qtaguid/stats` 文件
- 应用在监控期间没有网络活动
- 需要通过 `dumpsys netstats` 获取（框架已自动处理）

**磁盘IO为0的原因：**
- `/proc/pid/io` 需要 root 权限
- 普通设备无法直接获取应用级别的磁盘IO

**解决方案：**
1. 确保应用在监控期间有网络请求
2. 使用 root 设备可获取磁盘IO数据
3. Debug 版应用可通过 `run-as` 命令获取部分数据
4. 查看日志了解详细的数据采集过程

### Q9: 如何使用截图分析和数据处理工具？

**截图分析工具：**
```python
from utils.screenshot_analyzer import ScreenshotAnalyzer

analyzer = ScreenshotAnalyzer()
# 比较两张截图
diff_info = analyzer.compare_images("before.png", "after.png")
print(f"差异百分比: {diff_info['diff_percentage']:.2f}%")
```

**数据处理工具：**
```python
from utils.data_processor import DataProcessor

processor = DataProcessor()
# 加载CSV数据
df = processor.load_csv("performance_data.csv")
# 计算统计信息
stats = processor.calculate_statistics(df, "cpu_usage")
print(f"平均CPU使用率: {stats['mean']:.2f}%")
```

### Q10: ADB命令执行超时怎么办？

**常见原因：**
- 设备响应缓慢
- 命令执行时间较长（如录屏）
- ADB服务异常

**解决方案：**
1. 重启 ADB 服务：`adb kill-server && adb start-server`
2. 检查设备连接状态
3. 框架会自动重试失败的命令（最多3次）
4. 长时间命令（如录屏）已自动设置更长的超时时间

### Q11: 如何使用测试策略优化功能？

**快速测试：**
```bash
python run_tests.py --strategy quick --test-type all
# 预估时长：5-10分钟
```

**智能测试选择：**
```bash
python run_tests.py --smart-select --strategy quick
# 根据Git变更自动选择测试类型
```

**性能基线检查：**
```bash
python run_tests.py --baseline-check --strategy standard
# 首次运行建立基线，后续运行自动对比
```

详细说明请参考：[测试策略使用指南](docs/TEST_STRATEGY_GUIDE.md)

### Q12: 报告中的执行摘要和评分是什么意思？

**执行摘要**是报告开头的关键指标总览，包括：
- **综合评分**：0-100分，快速判断整体性能
- **各项评分**：启动、内存、FPS、网络、电池的独立评分
- **问题统计**：按优先级分类的问题数量

**评分标准：**
- 80-100分：优秀（绿色）✅
- 60-79分：良好（黄色）⚠️
- 40-59分：一般（橙色）⚠️
- 0-39分：较差（红色）❌

### Q13: 如何查看历史对比和趋势分析？

历史对比和趋势分析需要至少运行2次测试：

1. **首次运行**：建立历史记录
2. **后续运行**：自动对比上次测试

报告中的"历史对比分析"部分会显示：
- 与上次测试的指标对比
- 变化量和变化率
- 趋势方向（改善/退化）

"性能趋势分析"部分会显示最近30天的趋势。

### Q14: 如何导出PDF/Excel报告？

报告生成后，在HTML报告页面底部有导出按钮：
- 点击"📊 导出Excel"下载Excel报告
- 点击"📄 导出PDF"下载PDF报告

或者直接访问报告目录：
```bash
reports/full_report_YYYYMMDD_HHMMSS/
├── performance_report.xlsx  # Excel报告
└── performance_report.pdf   # PDF报告
```

### Q15: 内存测试显示"内存泄漏检测到"？

**说明：**
- 框架默认阈值为 50MB 内存增长
- 这可能是正常的缓存行为，不一定是内存泄漏

**判断方法：**
1. 查看内存增长趋势是否持续上升
2. 多次运行测试观察是否一致
3. 使用 Android Profiler 进一步分析

**调整阈值：**
在配置中可以自定义阈值：
```yaml
app:
  memory_threshold_mb: 100  # 自定义内存增长阈值
```

## 🔧 技术支持

### 检查清单

如果遇到问题，请检查：

1. **ADB连接**
   ```bash
   adb devices
   ```

2. **应用状态**
   ```bash
   adb shell dumpsys window windows | grep mCurrentFocus
   ```

3. **日志文件**
   ```bash
   tail -f logs/performance_tests.log
   ```

4. **配置文件**
   - 检查 `config/test_config.yaml` 配置是否正确
   - 检查设备ID是否匹配

### 依赖包

主要依赖包：
- `pandas` - 数据处理和Excel导出
- `openpyxl` - Excel文件操作
- `reportlab` - PDF报告生成
- `matplotlib` - 图表生成
- `pyyaml` - YAML配置解析
- `opencv-python` - 图像处理（可选，用于FPS分析）
- `pytest` - 单元测试框架

完整依赖列表见 `requirements.txt`

**安装所有依赖：**
```bash
pip install -r requirements.txt
```

### 开发工具

推荐使用以下工具进行开发：
- **类型检查**: `mypy` - 静态类型检查
- **代码格式化**: `black` - 代码格式化工具
- **代码检查**: `flake8` - 代码风格检查
- **测试覆盖**: `pytest-cov` - 测试覆盖率

```bash
# 安装开发工具
pip install mypy black flake8 pytest-cov

# 类型检查
mypy core/ utils/

# 代码格式化
black core/ utils/ tests/

# 代码检查
flake8 core/ utils/ tests/

# 测试覆盖率
pytest --cov=core --cov=utils tests/
```

## 🎯 测试策略优化

### 分层测试策略

框架提供三种预设测试策略，平衡测试覆盖率和测试时间：

| 策略 | 时长 | 适用场景 | 测试内容 |
|------|------|---------|---------|
| **Quick** | 5-10分钟 | 日常开发、CI/CD | 启动(3次)、内存(5次)、监控(60秒) |
| **Standard** | 15-30分钟 | 版本发布前 | 启动(10次)、内存(10次)、监控(5分钟) |
| **Deep** | 1-2小时 | 深度分析 | 启动(20次)、内存(20次)、监控(30分钟) |

### 智能测试选择

根据Git代码变更自动选择测试类型：

```bash
# 自动分析变更文件，只运行相关测试
python run_tests.py --smart-select --strategy quick
```

**自动映射规则：**
- Activity/Application变更 → 启动测试
- Fragment/ViewModel变更 → 内存测试
- Layout/UI变更 → UI测试
- API/Network变更 → 网络测试
- Service/Background变更 → 电池测试

### 性能基线检查

自动检测性能退化：

```bash
# 首次运行建立基线
python run_tests.py --baseline-check --strategy standard

# 后续运行自动对比基线
python run_tests.py --baseline-check --strategy standard
```

**功能特点：**
- 自动保存性能基线
- 检测超过20%的性能退化
- 自动更新基线
- 显示退化指标和改善指标

### 快速测试配置

快速测试模式优化了以下参数：

- 启动测试：3次迭代（标准10次）
- 内存测试：5次循环（标准10次）
- 监控时长：60秒（标准300秒）
- 采样间隔：2.0秒（标准1.0秒）
- Monkey事件：500个（标准5000个）
- 自动跳过电池测试（耗时较长）

详细说明请参考：[测试策略使用指南](docs/TEST_STRATEGY_GUIDE.md)

## 📝 更新日志

### v2.0.0 (最新) - 报告优化与测试策略优化

#### 🎉 报告优化（高优先级）

- ✅ **执行摘要**：一页关键指标总览，综合评分（0-100分）
- ✅ **性能评分系统**：自动评分各项性能（启动、内存、FPS、网络、电池）
- ✅ **问题优先级分类**：自动分类问题（CRITICAL/HIGH/MEDIUM/LOW）
- ✅ **问题诊断与建议**：智能分析问题原因，提供优化建议
- ✅ **时间序列图表**：交互式Chart.js图表展示性能趋势

#### 📊 报告增强（中优先级）

- ✅ **PDF/Excel导出**：支持导出PDF和Excel格式报告
- ✅ **历史对比分析**：与上次测试对比，显示性能变化
- ✅ **趋势分析**：最近30天的性能趋势分析
- ✅ **测试环境信息完善**：完整的设备、应用、网络、系统信息

#### 🚀 测试策略优化

- ✅ **分层测试策略**：快速测试（5-10分钟）、标准测试（15-30分钟）、深度测试（1-2小时）
- ✅ **智能测试选择**：根据Git代码变更自动选择测试类型
- ✅ **性能基线管理**：自动保存基线，检测性能退化
- ✅ **快速测试配置**：优化配置，缩短测试时间
- ✅ **测试跳过机制**：根据策略自动跳过耗时测试

#### 🔧 代码优化

- ✅ **功能拆分**：将run_tests.py功能拆分到专门的文件
  - `core/test_runner.py` - 测试执行逻辑
  - `utils/monkey_test.py` - Monkey测试模块
  - `utils/adb_utils.py` - ADB工具函数
  - `utils/logging_setup.py` - 日志配置模块
- ✅ **Monkey测试集成**：支持在内存测试和综合监控中执行Monkey测试
- ✅ **配置完善**：Monkey测试配置集成到主配置文件

### v1.2.0
- ✅ 日志系统改进
  - 支持按天轮转日志（`TimedRotatingFileHandler`）
  - 支持按大小轮转日志（`RotatingFileHandler`）
  - 可配置的轮转方式和保留数量
- ✅ ADB命令执行改进
  - 移除shell管道命令，提高兼容性
  - 支持自定义超时时间
  - 静默处理预期失败的命令（减少日志刷屏）
- ✅ 网络统计修复
  - 支持 Android 9+ 新的 netstats 格式
  - 修复 UID 查找和数据解析逻辑
- ✅ 内存指标修复
  - 改进 Java Heap 和 Native Heap 解析
  - 支持多种 `dumpsys meminfo` 输出格式
- ✅ 屏幕状态检测修复
  - 使用 `dumpsys display` 替代管道命令
  - 支持多种 Android 版本的输出格式
- ✅ 录屏功能修复
  - 修复长时间录屏超时问题
  - 支持自定义录屏超时时间

### v1.1.0
- ✅ 代码质量改进
  - 完整的类型提示（所有核心方法）
  - 详细的文档字符串（Google风格）
  - 输入验证工具集
  - 统一异常处理机制
- ✅ 错误处理增强
  - 智能重试机制（指数退避）
  - 错误恢复机制（自动修复常见问题）
  - 用户友好的错误消息
  - 详细的解决建议
- ✅ 单元测试
  - 设备管理器测试
  - 验证器测试
  - 重试机制测试
- ✅ 工具类
  - 截图分析工具
  - 数据处理工具

### v1.0.0
- ✅ 支持启动性能测试（冷启动、热启动）
- ✅ 支持内存测试（内存增长、泄漏检测）
- ✅ 支持网络性能测试
- ✅ 支持电池测试
- ✅ 支持UI渲染测试（FPS、滚动性能）
- ✅ 支持综合性能监控
- ✅ HTML报告生成（中英文双语）
- ✅ CSV数据导出
- ✅ 性能图表生成
- ✅ 日志系统
- ✅ 贷款APP专用操作流程
- ✅ 应用状态检测和等待机制
- ✅ 网络和磁盘IO增量计算
- ✅ CPU详细信息采集
- ✅ 线程统计和分类功能（按名称分类、按状态分类）

## ⚠️ 已知限制

### Android 版本兼容性

| 功能 | Android 9 以下 | Android 9+ | 说明 |
|------|---------------|------------|------|
| 网络流量统计 | ✅ | ✅ | Android 9+ 使用 `dumpsys netstats` |
| 磁盘 IO | ⚠️ | ⚠️ | 需要 root 权限 |
| CPU 使用率 | ✅ | ✅ | 完全支持 |
| 内存统计 | ✅ | ✅ | 完全支持 |
| FPS/帧率 | ✅ | ✅ | 通过 `gfxinfo` 获取 |
| 电池信息 | ✅ | ✅ | 完全支持 |
| 线程统计 | ✅ | ✅ | 部分线程可能无法获取名称 |

### 权限要求

| 数据类型 | 普通设备 | Root 设备 |
|----------|----------|-----------|
| CPU/内存/FPS | ✅ | ✅ |
| 网络流量 | ✅ | ✅ |
| 磁盘 IO | ❌ | ✅ |
| 系统级指标 | ❌ | ✅ |

### 其他限制

- **send-trim-memory**: 只能对后台应用执行，前台应用会失败
- **屏幕录制**: 最长支持 180 秒（Android 系统限制）
- **线程名称**: 部分系统线程名称可能被截断

## 📄 许可证

本项目采用 MIT 许可证。

## 👥 贡献

欢迎提交Issue和Pull Request！

### 贡献指南

1. **Fork项目**
2. **创建功能分支**: `git checkout -b feature/your-feature`
3. **提交更改**: `git commit -am 'Add some feature'`
4. **推送分支**: `git push origin feature/your-feature`
5. **提交Pull Request**

### 代码规范

- 遵循PEP 8代码风格
- 添加类型提示
- 编写文档字符串
- 添加单元测试
- 确保所有测试通过

### 相关文档

- [代码质量改进说明](CODE_QUALITY_IMPROVEMENTS.md)
- [错误处理改进说明](ERROR_HANDLING_IMPROVEMENTS.md)
- [项目完善说明](PROJECT_IMPROVEMENTS.md)
- [测试策略使用指南](docs/TEST_STRATEGY_GUIDE.md)
- [性能测试专业分析](PERFORMANCE_TEST_ANALYSIS.md)

## 🎨 报告优化版本对比

### 优化前 vs 优化后

| 功能 | 优化前 | 优化后 |
|------|--------|--------|
| **报告开头** | 直接显示配置信息 | ✅ 执行摘要（综合评分、问题统计） |
| **性能评估** | 仅显示原始数据 | ✅ 自动评分（0-100分）+ 状态 |
| **问题展示** | 所有问题平铺 | ✅ 按优先级排序（CRITICAL→HIGH→MEDIUM→LOW） |
| **问题分析** | 只显示数据 | ✅ 智能诊断 + 优化建议 |
| **数据可视化** | 静态图片 | ✅ 交互式Chart.js图表 |
| **历史对比** | 无 | ✅ 与上次测试对比 + 趋势分析 |
| **环境信息** | 基本信息 | ✅ 完整环境信息（设备、网络、系统） |
| **报告导出** | 仅HTML | ✅ PDF + Excel导出 |
| **测试时长** | 固定30分钟 | ✅ 快速测试5-10分钟 |

### 优化效果

- ⚡ **测试时间**：快速测试从30分钟缩短到5-10分钟（节省67%时间）
- 📊 **报告可读性**：执行摘要让非技术人员也能快速理解
- 🎯 **问题定位**：优先级分类让关键问题一目了然
- 💡 **可操作性**：每个问题都有具体的优化建议
- 📈 **趋势分析**：历史对比帮助发现性能退化
- 📄 **报告分享**：PDF/Excel导出便于离线查看和分享

---

**注意：** 本框架主要用于Android APP性能测试，需要设备已开启USB调试模式。测试过程中会执行自动化操作，请确保测试环境安全。