后端测试验证规则

一、强制要求

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

1. 新功能必须有测试

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

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

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

1. 测试必须全部通过

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

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

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

二、验证命令

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)

1. 实现功能代码

1. 运行测试验证

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

1. 测试通过后才算完成

4.2 修改现有功能时

1. 先找到相关测试文件

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

1. 理解当前测试的预期行为

1. 修改业务代码

1. 同步更新测试用例

• 如果返回值/行为变了 → 更新测试的 assert 语句
• 如果新增了字段/参数 → 新增测试覆盖
• 如果删除了功能 → 删除相关测试

1. 运行测试验证

   cd backend && uv run pytest tests/ -v

4.3 修复 Bug 时

1. 先写失败测试（复现 Bug）
2. 修复代码
3. 验证测试通过
4. 运行完整测试套件确保无回归

4.4 重构时

1. 先运行现有测试确保通过
2. 进行重构
3. 重新运行测试确保通过

五、测试编写规范

5.1 测试函数命名

def test_<被测对象>_<场景>_<预期结果>():
    # 例如：
    def test_create_agent_with_valid_data_returns_agent():
    def test_create_agent_with_empty_name_raises_error():

5.2 测试结构（AAA 模式）

def test_example():
    # Arrange - 准备测试数据
    input_data = {...}
    
    # Act - 执行被测代码
    result = function_under_test(input_data)
    
    # Assert - 验证结果
    assert result == expected

5.3 使用 fixtures

# conftest.py
@pytest.fixture
def sample_agent():
    return Agent(name="test", type="faq")

# test_file.py
def test_agent_update(sample_agent):
    sample_agent.name = "updated"
    assert sample_agent.name == "updated"

六、完成标准

功能完成的检查清单：

• [ ] 新增代码有对应的测试用例
• [ ] 修改的代码已同步更新相关测试用例
• [ ] 测试覆盖正常路径和异常路径
• [ ] 所有测试通过：uv run pytest tests/ -v
• [ ] 代码质量检查通过：uv run ruff check --fix
• [ ] 无跳过或禁用的测试
• [ ] 测试用例反映当前最新业务逻辑

验证流程：

# 1. 运行测试
cd backend && uv run pytest tests/ -v

# 2. 运行代码质量检查
cd backend && uv run ruff check --fix

# 两个命令都通过，功能才算完成

只有满足以上所有条件，功能才算真正完成。

七、常见场景示例

场景 1：修改函数返回值

# 原代码：返回 {"id": id, "name": name}
# 修改后：返回 {"id": id, "name": name, "status": "active"}

# 需要更新测试：
def test_get_item():
    result = get_item(1)
    assert result["id"] == 1
    assert result["name"] == "test"
    assert result["status"] == "active"  # 新增断言

场景 2：修改函数签名

# 原代码：def process(data)
# 修改后：def process(data, options=None)

# 需要新增测试：
def test_process_with_options():
    result = process(data, options={"flag": True})
    assert result == expected_with_options

场景 3：修改业务逻辑

# 原逻辑：价格 < 100 返回 "cheap"
# 新逻辑：价格 < 200 返回 "cheap"

# 需要更新测试：
def test_price_category_cheap():
    assert get_category(150) == "cheap"  # 原来期望 "normal"，现在期望 "cheap"