docs/development/COVERAGE_TESTING.md

# 覆盖率测试脚本使用指南

本项目提供了两个便于使用的覆盖率测试脚本，支持不同的使用场景。

## 📁 脚本文件

- `scripts/coverage.sh` - 简化版Bash脚本，适合日常使用
- `scripts/run_coverage.py` - 功能完整的Python脚本，支持高级选项

## 🚀 快速开始

### 基本用法（推荐）

```bash
# 进入项目根目录
cd /home/bmy001/Work/aichatbot

# 运行基本覆盖率测试
./scripts/coverage.sh

# 运行详细覆盖率测试（显示缺失行号）
./scripts/coverage.sh --detailed

# 生成HTML报告
./scripts/coverage.sh --html

# 运行完整分析
./scripts/coverage.sh --detailed --html --analysis
```

### 使用Python脚本

```bash
# 基本用法
python scripts/run_coverage.py

# 详细报告
python scripts/run_coverage.py --detailed

# 生成HTML报告
python scripts/run_coverage.py --format html

# 运行模块分析
python scripts/run_coverage.py --analysis

# 组合使用
python scripts/run_coverage.py --format both --detailed --analysis --clean
```

## 📊 脚本功能

### coverage.sh (Bash脚本)

**优点**：
- 简单易用，启动快速
- 自动环境管理
- 清理缓存文件
- 支持超时控制

**选项**：
- `-d, --detailed` - 显示详细覆盖率报告（缺失行号）
- `-h, --html` - 生成HTML报告
- `-a, --analysis` - 运行模块覆盖率分析
- `-t, --timeout N` - 设置超时时间（默认：180秒）
- `--help` - 显示帮助信息

### run_coverage.py (Python脚本)

**优点**：
- 功能更完整
- 更好的错误处理
- 支持模块选择
- 丰富的报告格式

**选项**：
- `--format/-f {term,html,both}` - 报告格式
- `--detailed/-d` - 显示详细信息
- `--analysis/-a` - 运行模块分析
- `--clean/-c` - 测试前清理缓存
- `--timeout/-t N` - 超时时间
- `--modules/-m` - 指定测试模块

## 🎯 使用场景

### 日常开发检查

```bash
# 快速检查当前覆盖率
./scripts/coverage.sh

# 查看具体缺失的代码行
./scripts/coverage.sh -d
```

### 详细分析

```bash
# 生成完整的分析报告
./scripts/coverage.sh -d -h -a

# 或使用Python脚本
python scripts/run_coverage.py --format both --detailed --analysis
```

### 特定模块测试

```bash
# 只测试telegram模块
python scripts/run_coverage.py --modules telegram --detailed

# 测试多个模块
python scripts/run_coverage.py --modules telegram core --format html
```

## 📋 输出示例

### 基本覆盖率报告

```
🔍 运行覆盖率测试 (超时: 180s)...

Name                                               Stmts   Miss  Cover
------------------------------------------------------------------------
src/claude_agent/core/agent.py                       444    233    48%
src/claude_agent/telegram/message_handler.py         545     85    84%
src/claude_agent/utils/helpers.py                    134      0   100%
------------------------------------------------------------------------
TOTAL                                               4547   1550    66%

✅ 覆盖率测试完成
```

### 模块分析报告

```
🔬 分析各模块覆盖率...

模块覆盖率汇总:
------------------------
  storage: ✅ 84%
  telegram: ✅ 85%
  cli: ✅ 95%
  utils: ✅ 93%
  mcp: ✅ 100%
  core: ✅ 48%
```

## 🛠️ 故障排除

### 常见问题

1. **脚本无法执行**
   ```bash
   chmod +x scripts/coverage.sh
   ```

2. **虚拟环境不存在**
   ```bash
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   ```

3. **测试超时**
   ```bash
   # 增加超时时间
   ./scripts/coverage.sh --timeout 300
   ```

4. **缓存问题**
   ```bash
   # 清理缓存后再测试
   python scripts/run_coverage.py --clean
   ```

## 💡 最佳实践

1. **定期检查**：建议每次提交代码前运行覆盖率测试
2. **HTML报告**：使用HTML报告深入分析未覆盖的代码
3. **模块分析**：使用模块分析功能识别需要改进的模块
4. **详细模式**：开发时使用详细模式查看具体缺失的代码行

## 🎯 覆盖率目标

- **整体目标**：≥ 80%
- **关键模块目标**：≥ 90%
- **工具模块目标**：≥ 95%
- **接口模块目标**：100%

## 📈 持续改进

使用这些脚本可以：
- 跟踪覆盖率变化趋势
- 识别需要测试的代码区域
- 确保新功能有完整的测试覆盖
- 维护高质量的代码库