run-tests

后端测试验证规则

一、强制要求

当修改后端代码时，必须遵循以下规则：

1. 新功能必须有测试

   • 每个新增的函数/类必须有对应的单元测试
   • 测试文件放在 backend/tests/ 对应目录下
   • 测试函数命名：test_<功能名>_<场景>

2. 修改代码必须同步更新测试

   • 修改业务逻辑后，必须检查并更新相关测试用例
   • 如果修改导致测试失败，需判断是代码 bug 还是测试需要更新
   • 业务变更 → 更新测试用例
   • 代码 bug → 修复代码

3. 测试必须全部通过

   • 功能完成的标准：所有相关测试通过
   • 不允许跳过或注释掉失败的测试

4. 测试用例必须反映最新业务

   • 测试用例应该与当前业务逻辑保持一致
   • 修改功能时，同时更新测试的预期结果

二、验证命令

2.1 测试命令

# 运行所有测试
cd backend && uv run pytest tests/ -v

# 运行特定模块测试
cd backend && uv run pytest tests/<module>/ -v

# 运行单个测试文件
cd backend && uv run pytest tests/<module>/test_<name>.py -v

# 运行匹配名称的测试
cd backend && uv run pytest -k "<pattern>" -v

2.2 代码质量检查（必须）

# 测试通过后，必须运行 ruff 检查并自动修复
cd backend && uv run ruff check --fix

# 如果有无法自动修复的问题，手动修复后重新检查
cd backend && uv run ruff check

注意：测试通过 + ruff 检查通过，才算代码验证完成。

三、测试目录结构

backend/tests/
├── conftest.py          # 共享 fixtures
├── core/                # 核心模块测试
│   ├── test_config.py
│   └── test_errors.py
├── models/              # 数据模型测试
│   └── test_conversation.py
├── repositories/        # 仓库层测试
│   └── test_base.py
├── schemas/             # Schema 测试
│   ├── test_agent.py
│   ├── test_chat.py
│   ├── test_events.py
│   └── test_websocket.py
└── services/            # 服务层测试
    ├── test_conversation.py
    └── test_streaming.py

四、工作流程

4.1 新增功能时

1. 先写测试（推荐 TDD）

   # tests/services/test_new_feature.py
   def test_new_feature_basic():
       """测试新功能的基本场景"""
       result = new_feature(input)
       assert result == expected
   
   def test_new_feature_edge_case():
       """测试边界情况"""
       ...
   
   def test_new_feature_error_handling():
       """测试错误处理"""
       with pytest.raises(ExpectedError):
           new_feature(invalid_input)
   

2. 实现功能代码

3. 运行测试验证

   cd backend && uv run pytest tests/services/test_new_feature.py -v
   

4. 测试通过后才算完成

4.2 修改现有功能时

1. 先找到相关测试文件

   # 搜索相关测试
   grep -r "test_<功能名>" backend/tests/