import pytest

2025-11-25 20:55:09 +09:00
parent 2a85c03253
commit d7f00408e5
6 changed files with 603 additions and 0 deletions
@@ -0,0 +1,245 @@
+# 测试框架使用指南
+
+## 概述
+
+项目已配置 **pytest** 测试框架,相比你之前的手动测试方法,有以下优势:
+
+### ✅ 改进点
+
+| 旧方法 (Jupyter Notebook) | 新方法 (pytest) |
+|-------------------------|----------------|
+| 手动运行每个测试用例 | 自动发现和运行所有测试 |
+| 手动读取和对比文件 | 自动化断言和差异报告 |
+| 难以定位失败原因 | 清晰的错误堆栈和 diff |
+| 无法批量运行 | 支持参数化和并行测试 |
+| 无覆盖率统计 | 自动生成覆盖率报告 |
+
+## 快速开始
+
+### 1. 运行所有测试
+```bash
+python -m pytest
+```
+
+### 2. 运行特定测试文件
+```bash
+python -m pytest tests/test_playlist_merge.py -v
+```
+
+### 3. 在 VS Code 中运行
+- 按 `Ctrl+Shift+P`
+- 输入 "Run Task"
+- 选择 "运行所有测试" 或其他测试任务
+
+## 测试文件说明
+
+### 已创建的测试文件
+
+```
+tests/
+├── __init__.py              # 包初始化
+├── conftest.py              # pytest fixtures 和配置
+├── test_playlist_merge.py   # 播放列表合并测试
+└── README.md                # 详细测试指南
+```
+
+### 测试用例覆盖
+
+`test_playlist_merge.py` 包含:
+
+1. **基础功能测试** (`TestPlaylistMergeBasics`)
+   - `test_load_paths_removes_comments` - 测试路径加载
+   - `test_save_paths_adds_header` - 测试文件保存
+   - `test_empty_playlist_merge` - 测试空播放列表合并
+
+2. **本地优先测试** (`TestPlaylistMergeLocalPriority`)
+   - 参数化测试 case1-4 的本地优先合并
+   
+3. **远程优先测试** (`TestPlaylistMergeRemotePriority`)
+   - 参数化测试 case1-4 的远程优先合并
+
+4. **冲突检测测试** (`TestConflictDetection`)
+   - 测试冲突识别和解决
+
+## 常用命令
+
+### 基础运行
+```bash
+# 运行所有测试
+pytest
+
+# 详细输出
+pytest -v
+
+# 显示 print 输出
+pytest -s
+
+# 只运行特定测试
+pytest tests/test_playlist_merge.py::TestPlaylistMergeBasics::test_load_paths_removes_comments
+```
+
+### 测试筛选
+```bash
+# 运行特定 case
+pytest -k "case_num-1"
+
+# 运行包含特定关键字的测试
+pytest -k "local_priority"
+
+# 运行标记的测试
+pytest -m unit
+```
+
+### 调试和重试
+```bash
+# 失败时进入调试器
+pytest --pdb
+
+# 只运行上次失败的测试
+pytest --lf
+
+# 先运行失败的测试
+pytest --ff
+
+# 遇到第一个失败就停止
+pytest -x
+```
+
+### 覆盖率报告
+```bash
+# 生成覆盖率报告
+pytest --cov=app --cov-report=html
+
+# 在浏览器中查看
+# 打开 htmlcov/index.html
+
+# 终端中显示覆盖率
+pytest --cov=app --cov-report=term
+```
+
+## 编写新测试
+
+### 1. 创建测试文件
+在 `tests/` 目录下创建 `test_<feature>.py`
+
+### 2. 编写测试类和函数
+```python
+import pytest
+
+class TestMyFeature:
+    """测试我的功能"""
+    
+    def test_basic_case(self):
+        """测试基本用例"""
+        result = my_function()
+        assert result == expected_value
+    
+    @pytest.mark.parametrize("input,expected", [
+        (1, 2),
+        (2, 4),
+        (3, 6),
+    ])
+    def test_multiple_cases(self, input, expected):
+        """参数化测试多个用例"""
+        assert my_function(input) == expected
+```
+
+### 3. 使用 fixtures
+```python
+@pytest.fixture
+def sample_data():
+    """提供测试数据"""
+    return {"key": "value"}
+
+def test_with_fixture(sample_data):
+    assert sample_data["key"] == "value"
+```
+
+## 与旧测试方法的对比
+
+### 旧方法 (test.ipynb)
+```python
+# 手动循环和对比
+for i in range(len(test_playlists[1])):
+    with open(test_playlists[1][i], 'r', encoding='utf-8') as f1, \
+         open(target_playlists[i], 'r', encoding='utf-8') as f2:
+        content1 = f1.read()
+        content2 = f2.read()
+        # 手动处理和对比...
+        if content1 == content2:
+            print(f"Test case {i+1} passed.")
+        else:
+            print(f"Test case {i+1} failed.")
+```
+
+### 新方法 (pytest)
+```python
+@pytest.mark.parametrize("case_num", [1, 2, 3, 4])
+def test_merge_local_priority(case_num, tmp_path):
+    """自动运行所有用例,失败时显示详细 diff"""
+    # 加载输入
+    base_text = load_file(f"case{case_num}.m3u")
+    # ... 执行测试
+    result = merge_playlists(base_text, local_text, remote_text)
+    # 自动断言和差异报告
+    assert_playlists_equal(actual_file, expected_file)
+```
+
+## 持续集成
+
+可以将测试集成到 CI/CD 流程:
+
+```yaml
+# .github/workflows/test.yml (示例)
+name: Tests
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+      - name: Run tests
+        run: pytest --cov=app
+```
+
+## 最佳实践
+
+1. **测试命名** - 使用清晰描述性的名称
+2. **独立性** - 每个测试应该独立运行
+3. **快速** - 单元测试应该快速执行
+4. **明确** - 一个测试只测一个功能点
+5. **维护** - 定期更新测试用例
+
+## 故障排除
+
+### pytest 找不到
+```bash
+python -m pip install pytest pytest-cov
+```
+
+### 导入错误
+确保项目根目录在 Python 路径中:
+```python
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent))
+```
+
+### 测试发现失败
+检查 `pytest.ini` 配置和文件命名是否符合规范。
+
+## 下一步
+
+- [ ] 为其他模块添加测试 (如 `plex_client.py`, `local_playlist.py`)
+- [ ] 添加集成测试
+- [ ] 配置 CI/CD 自动运行测试
+- [ ] 设置测试覆盖率目标 (如 >80%)
+
+## 参考资料
+
+- [pytest 官方文档](https://docs.pytest.org/)
+- [pytest-cov 文档](https://pytest-cov.readthedocs.io/)
+- 项目内测试: `tests/README.md`