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. 单元测试（推荐首先运行）

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

# 使用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环境：

# 运行完整模拟测试套件
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. 集成测试

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

# 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(): 环境变量测试

测试覆盖率

单元测试覆盖的功能

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

集成测试覆盖的功能

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

macOS模拟测试覆盖的场景

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

常见测试场景

场景1: 开发时快速验证

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

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

场景2: 验证特定配置

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

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

场景3: API功能验证

# 启动服务
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: 性能基准测试

# 启动服务
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示例

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:

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

故障排查

问题1: 导入错误

ModuleNotFoundError: No module named 'backend'

解决方案:

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

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

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

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

解决方案:

# 确保后端服务正在运行
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

解决方案:

# 增加超时时间
export TEST_TIMEOUT=300.0

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

最佳实践

1. 开发时: 频繁运行单元测试

   pytest backend/tests/test_tts_asr_unit.py -v --tb=short
   

2. 提交前: 运行完整测试套件

   pytest backend/tests/test_tts_asr_unit.py -v
   python backend/tests/simulate_macos.py --full-simulation
   

3. 部署前: 运行集成测试

   python backend/tests/test_tts_asr_integration.py
   

4. 调试时: 使用详细输出

   pytest backend/tests/test_tts_asr_unit.py -v -s --tb=long
   

测试报告

生成测试覆盖率报告：

# 安装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修复说明
• 环境变量配置
• API文档

---

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