# 端到端测试故障排查指南

## ⚠️ 测试卡住的常见原因

### 1. **首次运行下载模型**（最常见）
**症状**：CPU 占用不高，测试长时间无响应

**原因**：
- FunASR 模型首次运行需要下载（约 1-2GB）
- 下载速度取决于网络
- 下载过程中测试会卡住等待模型加载

**解决方案**：
```bash
# 手动预下载模型
python -c "from app.asr.asr_service import ASRService; ASRService()"
```

或等待 10-30 分钟（取决于网络）

---

### 2. **模型加载缓慢**
**症状**：CPU 占用低，内存占用逐渐上升

**原因**：
- ASR 模型很大（Paraformer 约 200MB+）
- CPU 加载模型需要时间（30 秒 -2 分钟）
- 首次加载会初始化多个组件

**解决方案**：
- 耐心等待首次加载
- 后续测试会快很多（模型已缓存）
- 使用 GPU 可加速（如果有）

---

### 3. **音频/视频文件过大**
**症状**：处理时间超长

**原因**：
- 长音频处理时间与长度成正比
- 1 分钟音频 ≈ 10-30 秒处理时间（CPU）
- 视频需要先提取音频

**解决方案**：
```yaml
# 在 test_config.yaml 中使用较小的测试文件
test_files:
  primary_video: "input/short.AVI"  # 使用短文件
```

---

### 4. **pytest-timeout 未安装**
**症状**：测试卡住后不会自动超时

**解决方案**：
```bash
pip install pytest-timeout
```

---

## 🔍 快速诊断命令

### 检查测试环境
```bash
python test/real/check_e2e.py
```

### 运行最简单的测试（不卡）
```bash
# 只运行文件验证测试（立即完成）
pytest test/real/test_real_e2e.py::TestVideoFileValidation -v

# 只运行错误处理测试（不依赖 ASR）
pytest test/real/test_real_e2e.py::TestErrorHandling -v
```

### 运行单个 ASR 测试（带详细输出）
```bash
# -s 显示 print 输出，便于观察进度
pytest test/real/test_real_e2e.py::TestASRRecognition::test_recognize_audio_file -v -s --timeout=600
```

### 查看模型缓存
```bash
# 检查模型是否已下载
dir app\asr /s /b | findstr ".pt"
```

---

## 🚀 推荐的测试流程

### 第一步：预下载模型（重要！）
```bash
# 在运行测试前，先手动加载一次模型
python -c "from app.asr.asr_service import ASRService; s = ASRService(); print('模型加载完成')"
```

### 第二步：运行快速验证测试
```bash
# 验证测试环境正常
pytest test/real/test_real_e2e.py::TestVideoFileValidation -v
pytest test/real/test_real_e2e.py::TestAudioFileValidation -v
pytest test/real/test_real_e2e.py::TestErrorHandling -v
```

### 第三步：运行单个 ASR 测试
```bash
# 使用短音频文件测试
pytest test/real/test_real_e2e.py::TestASRRecognition::test_recognize_audio_file -v -s
```

### 第四步：运行完整测试
```bash
# 所有端到端测试
pytest test/real/ -v -s --timeout=600
```

---

## 📊 预期处理时间参考

| 测试类型 | 文件大小 | CPU 时间 | GPU 时间 |
|---------|---------|---------|---------|
| 文件验证 | - | <1 秒 | <1 秒 |
| 错误处理 | - | <1 秒 | <1 秒 |
| ASR 识别（短音频） | 10MB | 30-60 秒 | 10-20 秒 |
| ASR 识别（长音频） | 50MB | 2-5 分钟 | 30-60 秒 |
| 视频转码 | 100MB | 1-3 分钟 | 30-60 秒 |

---

## 💡 优化建议

### 1. 使用更小的测试文件
```yaml
# test_config.yaml
test_files:
  primary_video: "input/short.AVI"  # 使用短文件
```

### 2. 跳过慢速测试
```bash
# 只运行快速测试
pytest test/real/ -v -m "not slow"
```

### 3. 并行测试（如果多个文件）
```bash
pip install pytest-xdist
pytest test/real/ -v -n 4  # 4 个进程并行
```

### 4. 使用 GPU（如果有）
```python
# 在 asr_service.py 中
service = ASRService(device='cuda')
```

---

## 🆘 仍然卡住怎么办？

### 方法 1：查看堆栈跟踪
按 `Ctrl+C` 中断测试，查看卡在哪里

### 方法 2：增加超时时间
```bash
pytest test/real/ -v --timeout=1200  # 20 分钟超时
```

### 方法 3：使用更短的测试文件
```bash
# 修改 test_config.yaml
primary_video: "input/short.AVI"
```

### 方法 4：检查日志
```bash
# 查看详细输出
pytest test/real/ -v -s 2>&1 | tee test.log
```

---

## ✅ 正常测试的标志

1. **首次运行**：
   - 模型下载：10-30 分钟（网络依赖）
   - 模型加载：30 秒 -2 分钟
   - 后续运行：快 10 倍

2. **处理过程**：
   - CPU 占用：50-100%（正常推理）
   - 内存占用：2-4GB（模型加载）
   - 磁盘 IO：中等（读写临时文件）

3. **完成标志**：
   - 看到 `✓` 标记
   - 显示处理时间
   - 生成结果文件

---

## 📝 测试输出示例

```
test/real/test_real_e2e.py::TestASRRecognition::test_recognize_audio_file

使用测试音频：VID_20251031_132320_019_mono.wav (5.23 MB)

开始测试音频识别：VID_20251031_132320_019_mono.wav
音频识别耗时：45.32 秒
✓ 音频识别成功，task_id: abc123...

PASSED [100%]
```

---

## 🔗 相关文档

- [测试配置文件](test_config.yaml) - 修改测试文件路径
- [测试代码](test_real_e2e.py) - 查看测试逻辑
- [pytest 文档](https://docs.pytest.org/) - pytest 使用