第5.5节:Python单元测试进阶

《Python AI 应用开发入门》第 5.5 节。

使用依赖注入、Fake、Mock 和 monkeypatch 隔离模型服务，并验证成功、超时、限流与服务异常。

本节目标

学完本节后，你应当能够：

1. 1. 说明单元测试为什么要隔离模型服务。
2. 2. 通过依赖注入替换外部客户端。
3. 3. 使用 Fake 和 Mock 控制依赖行为。
4. 4. 验证结果以及关键调用。
5. 5. 使用 side_effect 覆盖外部异常。
6. 6. 正确使用 patch() 和 monkeypatch。
7. 7. 避免过度 Mock，并保证单元测试离线运行。

1. 先隔离外部边界

单元测试直接调用真实模型服务会带来这些问题：

• • 得联网，还得有真实密钥。
• • 可能真的产生费用。
• • 响应快慢不稳定。
• • 模型给出的答案随时会变。
• • 服务一限流或者一故障，本地测试就跟着红。
• • 很难精确制造超时、限流等情况。

默认单元测试应当离线、快速并且结果可重复。真实服务的连通性属于少量、受控的集成测试。

测试中顶替真实依赖的对象称为测试替身：

需要清楚、可复用的简化实现时用 Fake；需要按测试配置返回值、异常和调用断言时用 Mock。无论使用哪一种，都先把模型客户端收敛成小接口：

from dataclasses import dataclassfrom typing import Protocol@dataclass(frozen=True)class ModelResponse:    content: str    model: strclass ModelClient(Protocol):    def generate(self, prompt: str) -> ModelResponse:        ...

服务通过构造方法接收客户端：

class ChatService:    def __init__(self, model_client: ModelClient) -> None:        self._model_client = model_client    def ask(self, question: str) -> ModelResponse:        cleaned_question = question.strip()        if not cleaned_question:            raise ValueError("问题不能为空")        prompt = f"请简洁回答：{cleaned_question}"        return self._model_client.generate(prompt)

这种做法叫依赖注入：ChatService 不负责创建真实客户端，而是接收外部传入的实现。测试可以换成替身，业务代码也不会绑定某个供应商。

2. 用 Fake 验证业务结果

Fake 就是一个普通的 Python 类：

class FakeModelClient:    def __init__(self, content: str = "这是测试回答") -> None:        self.content = content        self.prompts: list[str] = []    def generate(self, prompt: str) -> ModelResponse:        self.prompts.append(prompt)        return ModelResponse(            content=self.content,            model="fake-model",        )

先测成功路径：

def test_ask_returns_fake_model_response():    client = FakeModelClient(content="列表是有序容器")    service = ChatService(client)    result = service.ask("什么是列表？")    assert result.content == "列表是有序容器"    assert result.model == "fake-model"

还可以顺便验证服务有没有拼出正确的 Prompt：

def test_ask_builds_prompt_from_cleaned_question():    client = FakeModelClient()    service = ChatService(client)    service.ask("  什么是字典？  ")    assert client.prompts == ["请简洁回答：什么是字典？"]

Fake 代码直观、容易调试，适合多个测试复用。

3. 用 Mock 控制行为并验证调用

标准库的 unittest.mock 可以创建随时配置的 Mock 对象：

from unittest.mock import Mockdef test_ask_returns_configured_response():    client = Mock(spec=ModelClient)    client.generate.return_value = ModelResponse(        content="元组是不可变序列",        model="mock-model",    )    service = ChatService(client)    result = service.ask("什么是元组？")    assert result.content == "元组是不可变序列"

return_value 设置返回结果，spec=ModelClient 则限制 Mock 只能使用接口中存在的属性。Mock 还会记录调用：

def test_ask_calls_model_once_with_expected_prompt():    client = Mock(spec=ModelClient)    client.generate.return_value = ModelResponse(        content="回答",        model="mock-model",    )    service = ChatService(client)    service.ask("什么是集合？")    client.generate.assert_called_once_with(        "请简洁回答：什么是集合？"    )

常用断言包括：

client.generate.assert_called_once()client.generate.assert_called_once_with("预期参数")client.generate.assert_not_called()

如果空问题应在本地被拦下，还可以验证模型没有被调用：

import pytestdef test_empty_question_does_not_call_model():    client = Mock(spec=ModelClient)    service = ChatService(client)    with pytest.raises(ValueError, match="不能为空"):        service.ask("   ")    client.generate.assert_not_called()

结果断言与交互断言回答不同问题：

• • 结果断言：调用完之后，得到了什么结果或状态？
• • 交互断言：依赖有没有被调用，调用了几次、参数对不对？

优先验证用户能感知的结果。只有外部调用的次数、参数或“不得调用”本身属于业务规则时，才增加交互断言。

4. 用 side_effect 覆盖失败路径

side_effect 可以让 Mock 抛出指定异常。业务代码通常应把供应商异常转换为应用自己的稳定错误：

class ProviderRateLimitError(Exception):    passclass ProviderServiceError(Exception):    passclass ModelUnavailableError(Exception):    pass

然后由服务负责把各种底层错误，转换成稳定的领域错误：

class ChatService:    def __init__(self, model_client: ModelClient) -> None:        self._model_client = model_client    def ask(self, question: str) -> ModelResponse:        cleaned_question = question.strip()        if not cleaned_question:            raise ValueError("问题不能为空")        prompt = f"请简洁回答：{cleaned_question}"        try:            return self._model_client.generate(prompt)        except TimeoutError as error:            raise ModelUnavailableError("模型响应超时，请稍后重试") from error        except ProviderRateLimitError as error:            raise ModelUnavailableError("请求过于频繁，请稍后重试") from error        except ProviderServiceError as error:            raise ModelUnavailableError("模型服务暂时不可用") from error

超时、限流和服务故障的测试结构相同，可以用参数化测试覆盖：

@pytest.mark.parametrize(    ("provider_error", "expected_message"),    [        (TimeoutError("timeout"), "响应超时"),        (ProviderRateLimitError("429"), "请求过于频繁"),        (ProviderServiceError("503"), "暂时不可用"),    ],)def test_ask_converts_provider_errors(provider_error, expected_message):    client = Mock(spec=ModelClient)    client.generate.side_effect = provider_error    service = ChatService(client)    with pytest.raises(ModelUnavailableError, match=expected_message):        service.ask("你好")    client.generate.assert_called_once()

side_effect 也可以接收结果或异常列表，用来模拟连续调用；序列复杂时，写一个有明确状态的 Fake 通常更容易维护。

5. 正确使用 patch() 和 monkeypatch

有些遗留代码并没有做依赖注入：

# chat_core/service.pyfrom chat_core.clients import create_default_clientdef ask_with_default_client(question: str) -> ModelResponse:    client = create_default_client()    return client.generate(question)

这时测试可以临时把 create_default_client 替换掉：

from unittest.mock import Mock, patchdef test_ask_with_default_client_uses_created_client():    fake_client = Mock(spec=ModelClient)    fake_client.generate.return_value = ModelResponse(        "测试回答",        "mock-model",    )    with patch(        "chat_core.service.create_default_client",        return_value=fake_client,    ) as factory:        result = ask_with_default_client("问题")    assert result.content == "测试回答"    factory.assert_called_once_with()    fake_client.generate.assert_called_once_with("问题")

这里必须替换 chat_core.service.create_default_client，因为被测代码从 service.py 的命名空间查找这个名称。patch() 的原则是：替换被测代码查找名称的地方。如果设计还能调整，优先使用依赖注入。

pytest 的 monkeypatch 适合临时修改环境变量或对象属性：

import osdef read_model_name() -> str:    return os.environ.get("CHAT_MODEL", "local-echo")

对应的测试：

def test_read_model_name_uses_environment(monkeypatch):    monkeypatch.setenv("CHAT_MODEL", "test-model")    assert read_model_name() == "test-model"def test_read_model_name_uses_default_when_missing(monkeypatch):    monkeypatch.delenv("CHAT_MODEL", raising=False)    assert read_model_name() == "local-echo"

测试结束后，pytest 会自动撤销改动。替换时间函数等对象属性时使用 monkeypatch.setattr()，原则同样是替换被测代码实际访问的对象。

6. 设计外部依赖测试

调用外部模型时，至少要考虑这么几种情况：

实现重试时，还要验证可重试异常、次数上限、调用参数和最终失败。测试中不要真的等待，把等待函数作为依赖传入或临时替换。

出现下面这些信号，说明 Mock 用得过多：

• • 每个测试都要配置十几个内部方法。
• • 只是重命名一个私有方法，一大片测试就跟着挂。
• • 测试几乎把生产代码的执行步骤抄了一遍。
• • 所有对象都被 Mock 掉，真实业务逻辑基本没跑到。
• • 测试全绿，但真实对象凑在一起却协作不起来。

改进原则是：

1. 1. 只在外部边界用替身，比如模型、网络、时钟和文件系统。
2. 2. 自己的数据类和纯函数，直接用真实对象。
3. 3. 优先验证公开结果，必要时再验证关键交互。
4. 4. 用一两个小 Fake，代替一大堆脆弱的 Mock 配置。
5. 5. 保留少量集成测试，确认真实组件能协作。

动手实践：测试模型调用边界

1. 1. 编写 FakeModelClient，保存收到的 Prompt，并验证成功结果和 Prompt 清理。
2. 2. 使用带 spec 的 Mock，分别模拟超时、限流和服务故障。
3. 3. 验证应用抛出的稳定异常，以及模型调用次数和参数。
4. 4. 用 monkeypatch 提供测试环境变量，确认测试没有真实密钥和网络请求。

随堂小测

1. 1. 单元测试为什么不该调用真实模型服务？
2. 2. Fake 和 Mock 主要有什么区别？
3. 3. 什么是依赖注入？
4. 4. return_value 和 side_effect 分别控制什么？
5. 5. 什么时候需要交互断言？
6. 6. patch() 为什么要替换名称的使用位置？
7. 7. Mock 用过头会带来什么问题？

参考答案

1. 1. 它依赖网络、密钥、费用和不稳定的响应，做不到快速、确定、离线。
2. 2. Fake 是一个小型但能真正运行的实现；Mock 更适合逐个测试配置行为，并记录调用情况。
3. 3. 对象不自己创建依赖，而是由外部通过参数等方式传进来。
4. 4. 前者配置调用的返回值，后者可以配置异常、函数，或一串连续结果。
5. 5. 当外部调用的次数、参数，或者“不得调用”本身就是业务要求时。
6. 6. 被测代码在自己的命名空间查找名称，替换原始定义未必影响已经导入的名称。
7. 7. 测试会被内部实现锁死、难以维护，而且关键业务逻辑可能根本没运行。