llm-in-text/backend/tests/TESTING_GUIDE.md

# TTS/ASR 测试指南

本文档提供完整的测试脚本使用说明，包括单元测试、集成测试和macOS环境模拟测试。

## 测试脚本概览

| 脚本 | 位置 | 用途 | 需要后端服务 |
|------|------|------|--------------|
| `test_tts_asr_unit.py` | `backend/tests/` | 单元测试（设备检测、模型选择、音频处理） | 否 |
| `test_tts_asr_integration.py` | `backend/tests/` | 集成测试（API端点、完整流程） | 是 |
| `simulate_macos.py` | `backend/tests/` | macOS环境模拟（在非Mac环境测试） | 否 |

## 快速开始

### 1. 单元测试（推荐首先运行）

单元测试不需要实际运行模型或后端服务，测试代码逻辑：

```bash
# 使用pytest运行（推荐）
pytest backend/tests/test_tts_asr_unit.py -v

# 直接运行
python backend/tests/test_tts_asr_unit.py

# 运行特定测试类
pytest backend/tests/test_tts_asr_unit.py::TestAppleSiliconDetection -v

# 运行特定测试方法
pytest backend/tests/test_tts_asr_unit.py::TestAppleSiliconDetection::test_is_apple_silicon_on_darwin_arm64 -v
```

### 2. macOS环境模拟测试

在非macOS环境下模拟Apple Silicon环境：

```bash
# 运行完整模拟测试套件
python backend/tests/simulate_macos.py --full-simulation

# 仅模拟Apple Silicon环境并进入交互模式
python backend/tests/simulate_macos.py --apple-silicon

# 模拟特定设备
python backend/tests/simulate_macos.py --device mps
python backend/tests/simulate_macos.py --device cuda

# 运行特定测试
python backend/tests/simulate_macos.py --test device   # 设备检测
python backend/tests/simulate_macos.py --test memory   # 内存管理
python backend/tests/simulate_macos.py --test model    # 模型选择
python backend/tests/simulate_macos.py --test audio    # 音频处理
python backend/tests/simulate_macos.py --test env      # 环境变量
```

### 3. 集成测试

集成测试需要运行后端服务：

```bash
# 1. 启动后端服务（终端1）
python backend/main.py

# 2. 运行集成测试（终端2）
# 运行所有测试
python backend/tests/test_tts_asr_integration.py

# 运行特定测试
python backend/tests/test_tts_asr_integration.py --test config   # 配置端点
python backend/tests/test_tts_asr_integration.py --test status   # 状态端点
python backend/tests/test_tts_asr_integration.py --test warmup   # 预热测试
python backend/tests/test_tts_asr_integration.py --test tts      # TTS测试
python backend/tests/test_tts_asr_integration.py --test asr      # ASR测试
python backend/tests/test_tts_asr_integration.py --test perf     # 性能测试

# 自定义API地址
python backend/tests/test_tts_asr_integration.py --url http://localhost:8001 --key your-api-key
```

## 详细测试说明

### 单元测试详解

#### TestAppleSiliconDetection

测试Apple Silicon检测功能：

- `test_is_apple_silicon_on_darwin_arm64`: 在Darwin/arm64环境检测
- `test_is_apple_silicon_on_windows`: 在Windows环境不应检测到
- `test_is_apple_silicon_on_linux`: 在Linux环境不应检测到

#### TestEnvironmentVariables

测试环境变量解析：

- `test_default_environment_values`: 验证默认值
- `test_custom_environment_values`: 验证自定义值

#### TestModelSizeSelection

测试模型大小选择：

- `test_whisper_model_sizes_mapping`: 模型大小映射验证
- `test_recommended_model_size_explicit`: 显式指定大小
- `test_invalid_model_size_falls_back`: 无效大小回退

#### TestAudioValidation

测试音频验证：

- `test_validate_empty_audio`: 空音频验证
- `test_validate_valid_wav_header`: 有效WAV头验证
- `test_validate_invalid_audio`: 无效音频验证

#### TestAudioResampling

测试音频重采样：

- `test_resample_same_rate`: 相同采样率
- `test_resample_different_rate`: 不同采样率重采样
- `test_resample_downsample`: 下采样

#### TestDeviceCapabilities

测试设备能力检测：

- `test_device_capabilities_dataclass`: 数据类验证
- `test_device_capabilities_with_mps`: MPS设备能力

#### TestModelCacheCheck

测试模型缓存检查：

- `test_cache_check_non_offline_mode`: 非离线模式
- `test_cache_check_offline_mode_missing`: 离线模式缺失模型

#### TestRequestResponseModels

测试API模型：

- `test_tts_request_model`: TTS请求模型
- `test_asr_request_model`: ASR请求模型
- `test_model_status_model`: 状态模型

### 集成测试详解

#### TTSASRIntegrationTest

主要集成测试：

- `test_01_config_endpoint`: 配置端点测试
- `test_02_status_endpoint`: 状态端点测试
- `test_03_warmup_endpoint`: 预热端点测试
- `test_04_tts_endpoint_basic`: TTS基本功能测试
- `test_05_asr_endpoint_basic`: ASR基本功能测试
- `test_06_api_key_validation`: API密钥验证测试
- `test_07_tts_long_text`: TTS长文本测试

#### PerformanceTest

性能测试：

- `test_tts_latency`: TTS延迟测试

### macOS模拟测试详解

#### MacOSSimulator类

提供以下模拟功能：

- `simulate_apple_silicon()`: 模拟Darwin/arm64环境
- `simulate_mps_device()`: 模拟MPS设备可用
- `simulate_cuda_device()`: 模拟CUDA设备可用
- `cleanup()`: 清理模拟环境

#### 独立测试函数

- `test_device_detection_on_apple_silicon()`: Apple Silicon设备检测
- `test_memory_management()`: 内存管理测试
- `test_model_size_selection()`: 模型大小选择测试
- `test_audio_processing()`: 音频处理测试
- `test_environment_variables()`: 环境变量测试

## 测试覆盖率

### 单元测试覆盖的功能

- [x] Apple Silicon检测逻辑
- [x] 环境变量解析和默认值
- [x] 模型大小选择和推荐
- [x] 音频数据验证
- [x] 音频重采样（多回退方案）
- [x] 设备能力检测数据结构
- [x] 模型缓存检查
- [x] API请求/响应模型

### 集成测试覆盖的功能

- [x] 配置端点（`/v1/tts-asr/config`）
- [x] 状态端点（`/v1/tts-asr/status`）
- [x] 预热端点（`/v1/tts-asr/warmup`）
- [x] TTS端点（`/v1/tts-asr/tts`）
- [x] ASR端点（`/v1/tts-asr/asr`）
- [x] API密钥验证
- [x] 长文本处理
- [x] 性能基准测试

### macOS模拟测试覆盖的场景

- [x] Apple Silicon环境模拟
- [x] MPS设备模拟
- [x] CUDA设备模拟
- [x] 系统内存模拟
- [x] 完整环境变量测试

## 常见测试场景

### 场景1: 开发时快速验证

```bash
# 快速单元测试
pytest backend/tests/test_tts_asr_unit.py -v --tb=short

# macOS模拟（完整）
python backend/tests/simulate_macos.py --full-simulation
```

### 场景2: 验证特定配置

```bash
# 设置环境变量后测试
export TTS_ASR_MODEL_SIZE=small
export TTS_ASR_QUANTIZE=true

# 运行测试
python backend/tests/simulate_macos.py --test model
```

### 场景3: API功能验证

```bash
# 启动服务
python backend/main.py

# 测试配置端点
python backend/tests/test_tts_asr_integration.py --test config

# 测试TTS功能
python backend/tests/test_tts_asr_integration.py --test tts

# 测试ASR功能
python backend/tests/test_tts_asr_integration.py --test asr
```

### 场景4: 性能基准测试

```bash
# 启动服务
python backend/main.py

# 运行性能测试
python backend/tests/test_tts_asr_integration.py --test perf
```

## 测试输出解读

### 成功示例

```
test_is_apple_silicon_on_darwin_arm64 ... ok
test_is_apple_silicon_on_windows ... ok
test_is_apple_silicon_on_linux ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.005s

OK
```

### 失败示例

```
test_device_detection_on_apple_silicon ... FAIL

======================================================================
FAIL: test_device_detection_on_apple_silicon
----------------------------------------------------------------------
Traceback (most recent call last):
  File "test_tts_asr_unit.py", line 45, in test_is_apple_silicon_on_darwin_arm64
    self.assertTrue(_is_apple_silicon())
AssertionError: False is not true

----------------------------------------------------------------------
Ran 1 tests in 0.002s

FAILED (failures=1)
```

## 持续集成配置

### GitHub Actions示例

```yaml
name: TTS/ASR Tests

on: [push, pull_request]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - name: Install dependencies
        run: |
          pip install -r backend/requirements.txt
          pip install pytest
      - name: Run unit tests
        run: pytest backend/tests/test_tts_asr_unit.py -v
      - name: Run macOS simulation
        run: python backend/tests/simulate_macos.py --full-simulation
```

### pytest配置

创建 `pytest.ini`:

```ini
[pytest]
testpaths = backend/tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = -v --tb=short
```

## 故障排查

### 问题1: 导入错误

```
ModuleNotFoundError: No module named 'backend'
```

**解决方案**:

```bash
# 确保在项目根目录运行
cd /path/to/llm-in-text

# 或设置PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
```

### 问题2: 后端服务连接失败

```
✗ 无法连接到服务: [Errno 111] Connection refused
```

**解决方案**:

```bash
# 确保后端服务正在运行
python backend/main.py

# 检查端口
lsof -i :8001

# 或使用自定义URL
python backend/tests/test_tts_asr_integration.py --url http://localhost:8001
```

### 问题3: 模型未加载

```
⚠ TTS失败（可能是模型未加载）
```

**解决方案**:

这是预期行为，表示模型需要时间下载。可以：

1. 等待模型下载完成
2. 使用预热端点: `POST /v1/tts-asr/warmup`
3. 启用离线模式（如果模型已下载）

### 问题4: 测试超时

```
httpx.ReadTimeout: timed out
```

**解决方案**:

```bash
# 增加超时时间
export TEST_TIMEOUT=300.0

# 或在测试脚本中修改
TEST_TIMEOUT = 300.0  # 5分钟
```

## 最佳实践

1. **开发时**: 频繁运行单元测试
   ```bash
   pytest backend/tests/test_tts_asr_unit.py -v --tb=short
   ```

2. **提交前**: 运行完整测试套件
   ```bash
   pytest backend/tests/test_tts_asr_unit.py -v
   python backend/tests/simulate_macos.py --full-simulation
   ```

3. **部署前**: 运行集成测试
   ```bash
   python backend/tests/test_tts_asr_integration.py
   ```

4. **调试时**: 使用详细输出
   ```bash
   pytest backend/tests/test_tts_asr_unit.py -v -s --tb=long
   ```

## 测试报告

生成测试覆盖率报告：

```bash
# 安装coverage
pip install pytest-cov

# 运行并生成报告
pytest backend/tests/test_tts_asr_unit.py --cov=backend.tts_asr --cov-report=html

# 查看报告
open htmlcov/index.html
```

## 相关文档

- [TTS/ASR修复说明](./TTS_ASR_MACOS_FIX.md)
- [环境变量配置](../README.md#ttsasr环境变量配置)
- [API文档](../README.md#api接口)

---

**更新日期**: 2026-04-06  
**维护者**: 项目开发团队