# sync_play_video 函数单元测试使用说明

## 概述

本文档介绍了 `sync_play_video` 函数的单元测试，该测试从配置文件中读取真实的 Kodi 客户端配置和声音设置，确保测试更贴近实际使用场景。

## 测试文件

- **测试文件**: `test_sync.py`
- **被测试函数**: `KodiServer.sync_play_video()`
- **配置文件**: 
  - `config/config.yaml` - 主配置文件（Kodi客户端配置）
  - `config/ButtonListenerTask.yaml` - 声音配置文件

## 配置文件结构

### config/config.yaml
```yaml
kodi_clients:
  - ip: 192.168.189.181
    port: 8080
    username: kodi
    password: 123
  - ip: 192.168.189.182
    port: 8080
    username: kodi
    password: 123
  # ... 更多客户端配置

video_paths:
  - /sdcard/Movies/0.mp4
  - /sdcard/Movies/硫酸钠.mp4
  # ... 更多视频路径
```

### config/ButtonListenerTask.yaml
```yaml
sound:
  client_index: 1  # 播放声音的客户端索引 (-1表示所有客户端)
  volume: 85       # 音量 (0-100)

video_paths:
  - /sdcard/Movies/0.mp4
  # ... 视频路径列表
```

## 测试用例说明

### 1. test_sync_play_video_no_clients
- **目的**: 测试没有客户端时的错误处理
- **验证**: 返回失败状态和相应错误消息

### 2. test_sync_play_video_with_config_clients_success
- **目的**: 测试使用配置文件中的客户端成功播放
- **特点**: 
  - 使用配置文件中的前3个客户端
  - 使用配置文件中的声音设置
  - 验证所有客户端都被正确调用

### 3. test_sync_play_video_with_config_sound_settings
- **目的**: 测试配置文件中的声音设置
- **验证**: 
  - 根据 `sound_client_index` 设置正确的音量
  - 验证打印的声音设置信息

### 4. test_sync_play_video_all_config_videos
- **目的**: 测试配置文件中的所有视频路径
- **特点**: 
  - 使用 `subTest` 分别测试每个视频路径
  - 只测试前3个视频路径以控制测试时间

### 5. test_sync_play_video_invalid_sound_client_index_with_config
- **目的**: 测试无效的声音客户端索引
- **验证**: 
  - 超出范围的索引会触发警告
  - 系统会回退到默认客户端

### 6. test_sync_play_video_client_failure_with_config
- **目的**: 测试客户端播放失败的情况
- **验证**: 
  - 部分客户端失败时的处理
  - 成功和失败客户端的正确分类

### 7. test_config_file_loading
- **目的**: 验证配置文件加载的正确性
- **验证**: 
  - 配置文件结构完整性
  - 配置值的合理性检查

### 8. test_sync_play_video_with_real_config_integration
- **目的**: 完整的集成测试
- **特点**: 
  - 使用真实配置文件的所有设置
  - 最多测试5个客户端
  - 输出详细的测试信息

## 运行测试

### 基本运行
```bash
python test_sync.py
```

### 运行特定测试
```bash
python -m unittest test_sync.TestSyncPlayVideoWithConfig.test_config_file_loading
```

### 详细输出
```bash
python -m unittest test_sync.TestSyncPlayVideoWithConfig -v
```

## 测试特点

### 1. 配置驱动
- 测试从真实配置文件读取设置
- 自动适应配置文件中的客户端数量
- 使用配置文件中的视频路径和声音设置

### 2. Mock 对象使用
- 使用 Mock 对象模拟 KodiClient
- 避免实际网络连接
- 可控制的测试环境

### 3. 异常处理测试
- 测试各种异常情况
- 验证错误处理逻辑
- 确保系统稳定性

### 4. 边界条件测试
- 无客户端情况
- 无效索引处理
- 配置文件缺失处理

## 测试输出示例

```
开始运行sync_play_video函数单元测试（从配置文件读取配置）...
======================================================================
test_config_file_loading ... ok
test_sync_play_video_all_config_videos ... ok
test_sync_play_video_client_failure_with_config ... ok
test_sync_play_video_invalid_sound_client_index_with_config ... ok
test_sync_play_video_no_clients ... ok
test_sync_play_video_with_config_clients_success ... ok
test_sync_play_video_with_config_sound_settings ... ok
test_sync_play_video_with_real_config_integration ... 

集成测试完成:
- 测试客户端数量: 5
- 声音客户端索引: 1
- 默认音量: 85
- 测试视频: /sdcard/Movies/0.mp4
ok

----------------------------------------------------------------------
Ran 8 tests in 0.113s

OK
======================================================================
测试完成！
运行测试数量: 8
失败数量: 0
错误数量: 0
```

## 注意事项

### 1. 配置文件依赖
- 确保 `config/config.yaml` 和 `config/ButtonListenerTask.yaml` 存在
- 配置文件格式必须正确
- 测试会自动检查配置文件是否存在

### 2. 测试环境
- 测试使用 Mock 对象，不需要真实的 Kodi 服务器
- 测试会跳过 `time.sleep()` 以加速执行
- 测试不会产生实际的网络流量

### 3. 扩展性
- 可以轻松添加新的测试用例
- 支持不同的配置文件结构
- 可以测试更多的边界条件

## 故障排除

### 配置文件不存在
```
错误：配置文件 config/config.yaml 不存在
```
**解决方案**: 确保配置文件存在且路径正确

### 配置文件格式错误
```
yaml.scanner.ScannerError: ...
```
**解决方案**: 检查 YAML 文件格式，确保语法正确

### 测试跳过
```
test_sync_play_video_all_config_videos ... skipped '配置文件中没有客户端配置'
```
**解决方案**: 检查配置文件中是否有 `kodi_clients` 配置

## 总结

这个测试套件提供了全面的 `sync_play_video` 函数测试，通过从配置文件读取真实设置，确保测试更贴近实际使用场景。测试覆盖了正常流程、异常处理、边界条件等各种情况，为代码质量提供了可靠保障。