为Python业务代码编写单元测试,怎样覆盖依赖调用失败后的异常处理分支?
依赖调用失败后的异常分支,单元测试要验证的不只是“抛出了异常”,还要确认业务代码是否把依赖异常转换成合适的业务异常、是否保留了原始异常,以及成功路径和非预期程序错误有没有被误处理。下面用一个支付网关调用说明如何实现:在业务方法中注入网关依赖,通过 Mock.side_effect 模拟超时和其他已知故障,再用 pytest.raises 检查异常类型与异常链。
这里的关键边界是:业务层只处理网关接口约定的异常,不把所有 Exception 都吞掉。对于支付超时,网关可能已经受理请求,只是响应没有及时返回,因此不能简单当成“支付失败”;业务异常应表达状态尚未确认,后续由调用方查询状态或按幂等规则处理。
先划清异常边界
测试之前,先确定哪些异常属于依赖故障,哪些属于业务结果,哪些属于代码缺陷。边界不清楚时,即使测试覆盖了 except 分支,也可能把真正的问题隐藏起来。
| 情况 | 业务层的处理方式 | 测试要确认的结果 |
|---|---|---|
| 网关响应超时 | 转换成“支付结果暂无法确认”一类业务异常 | 业务异常类型正确,原始超时异常保留为原因 |
| 网关明确报告调用故障 | 转换成业务层可识别的调用失败异常 | 走通用依赖故障分支,不泄露底层细节 |
| 网关调用成功 | 返回业务结果 | 返回值正确,调用参数正确 |
ValueError 等非网关异常 | 不应被网关故障处理代码捕获 | 原异常继续抛出,便于发现程序缺陷 |
如果网关还会返回“余额不足”“卡号无效”等业务拒绝结果,应把它们设计成明确的业务结果或专门的拒绝异常,不要一律归入网络故障。以下示例只覆盖调用超时与网关调用故障。
在业务方法中集中处理已知故障
示例项目把业务逻辑和测试分开放置:
project/
├── payment_service.py
└── tests/
└── test_payment_service.py
payment_service.py 定义网关接口、依赖异常和业务方法。真实网关实现可以在其他模块中提供;测试时则注入模拟对象,不需要建立网络连接。
from dataclasses import dataclass
from typing import Protocol
class GatewayError(Exception):
"""网关接口约定的调用故障基类。"""
class GatewayTimeout(GatewayError):
"""网关调用超时。"""
class GatewayUnavailable(GatewayError):
"""网关暂时不可用或调用失败。"""
class PaymentOutcomeUnknown(Exception):
"""支付请求已发出,但结果暂时无法确认。"""
class PaymentGatewayCallFailed(Exception):
"""支付网关调用失败。"""
@dataclass(frozen=True)
class ChargeResult:
transaction_id: str
@dataclass(frozen=True)
class PaymentReceipt:
order_id: str
transaction_id: str
class PaymentGateway(Protocol):
def charge(self, order_id: str, amount_cents: int) -> ChargeResult:
...
def pay_order(
order_id: str,
amount_cents: int,
gateway: PaymentGateway,
) -> PaymentReceipt:
try:
result = gateway.charge(order_id, amount_cents)
except GatewayTimeout as exc:
raise PaymentOutcomeUnknown(
"支付状态暂无法确认"
) from exc
except GatewayError as exc:
raise PaymentGatewayCallFailed(
"支付网关调用失败"
) from exc
return PaymentReceipt(
order_id=order_id,
transaction_id=result.transaction_id,
)
两个 except 分支的顺序不能颠倒。GatewayTimeout 是 GatewayError 的子类;如果先捕获 GatewayError,超时就会被通用故障分支提前处理,PaymentOutcomeUnknown 分支永远不会执行。

raise ... from exc 会把底层异常保存为新异常的 <strong>cause</strong>。调用方可以按业务异常进行处理,排查时也能查看原始原因。业务异常的消息不必复制网关返回的完整内容,避免把密钥、请求参数或第三方错误细节带入上层日志和响应。
超时尤其需要谨慎解释:客户端没有收到响应,不等于网关没有完成扣款。真实系统中,重复提交应结合幂等键、支付状态查询或业务侧防重机制处理;单元测试可以验证异常映射,但不能替代这些业务保障。
用 side_effect 触发指定异常分支
安装测试依赖后,可从项目根目录运行测试:
python -m pip install pytest
python -m pytest -q
下面的测试文件覆盖超时、其他网关故障、成功返回和非预期异常。每个测试都构造一份新的模拟网关,避免前一个测试留下的 side_effect 或调用记录影响后续测试。
import pytest
from unittest.mock import Mock
from payment_service import (
ChargeResult,
GatewayError,
GatewayTimeout,
GatewayUnavailable,
PaymentGateway,
PaymentGatewayCallFailed,
PaymentOutcomeUnknown,
PaymentReceipt,
pay_order,
)
def make_gateway():
return Mock(spec=PaymentGateway)
def test_timeout_becomes_unknown_payment_outcome():
gateway = make_gateway()
timeout = GatewayTimeout("read timed out")
gateway.charge.side_effect = timeout
with pytest.raises(PaymentOutcomeUnknown) as exc_info:
pay_order("order-1001", 2500, gateway)
assert exc_info.value.__cause__ is timeout
gateway.charge.assert_called_once_with("order-1001", 2500)
def test_other_gateway_error_becomes_call_failed():
gateway = make_gateway()
error = GatewayUnavailable("upstream unavailable")
gateway.charge.side_effect = error
with pytest.raises(PaymentGatewayCallFailed) as exc_info:
pay_order("order-1002", 3200, gateway)
assert exc_info.value.__cause__ is error
gateway.charge.assert_called_once_with("order-1002", 3200)
def test_success_returns_receipt():
gateway = make_gateway()
gateway.charge.return_value = ChargeResult(
transaction_id="txn-9001"
)
receipt = pay_order("order-1003", 1800, gateway)
assert receipt == PaymentReceipt(
order_id="order-1003",
transaction_id="txn-9001",
)
gateway.charge.assert_called_once_with("order-1003", 1800)
def test_unexpected_error_is_not_swallowed():
gateway = make_gateway()
bug = ValueError("invalid internal state")
gateway.charge.side_effect = bug
with pytest.raises(ValueError) as exc_info:
pay_order("order-1004", 1000, gateway)
assert exc_info.value is bug
side_effect 与 return_value 的区别
return_value 表示模拟调用正常返回什么对象。成功测试中,网关返回 ChargeResult,业务方法据此构造 PaymentReceipt。
side_effect 可以让模拟调用抛出异常。将异常实例赋给 gateway.charge.side_effect 后,调用 gateway.charge(...) 时就会抛出该异常。因此,超时测试实际走过的是 pay_order 中的超时处理分支,而不是只测试异常类本身。
测试同时检查了 <strong>cause</strong>。仅断言 pytest.raises(PaymentOutcomeUnknown),只能证明业务异常出现过;再确认它的原因对象就是预先设置的超时异常,才能验证异常转换时没有丢失故障来源。检查 assert_called_once_with(...) 则可确认业务代码确实使用预期的订单号和金额调用依赖。
Mock(spec=PaymentGateway) 会依据接口限制模拟对象的属性,拼错方法名时更容易在测试阶段发现问题。若测试不需要检查接口形状,普通 Mock() 也能工作,但接口约束通常更有助于维护。
为什么还要测试非预期异常
下面这种写法看起来可以统一返回友好错误,却会把编程错误也当成依赖故障:
try:
result = gateway.charge(order_id, amount_cents)
except Exception:
raise PaymentGatewayCallFailed("支付网关调用失败")
如果代码中出现 AttributeError、ValueError 或其他与网关接口无关的问题,这段处理会隐藏原始错误,让故障表现成网关不可用。示例中的 test_unexpected_error_is_not_swallowed 明确要求 ValueError 原样抛出,防止以后有人扩大捕获范围却没有相应评审。
当然,如果某个 SDK 的特定异常没有继承 GatewayError,业务层就不会捕获它。比较稳妥的做法是在 SDK 适配层将已知 SDK 异常转换成网关接口约定的异常,再让业务层只依赖这组稳定类型。具体应转换哪些异常,需要根据所用 SDK 的文档和实际接口确认;不要为了“保险”在业务层捕获所有异常。
根据项目结构调整测试方式
把网关注入 pay_order,可以直接在测试中提供模拟对象,不需要修改全局状态。若现有代码在业务函数内部创建依赖,例如:
def pay_order(order_id, amount_cents):
gateway = RealPaymentGateway()
...
测试就无法直接传入 Mock。可以考虑将依赖通过函数参数或构造函数注入;如果暂时不能调整结构,也可以用 monkeypatch 替换业务模块中实际使用的构造对象。
替换位置要看被测代码在哪里查找名称,而不是只看类最初定义在哪个文件。例如,若 payment_service.py 中写了 from gateway_client import RealPaymentGateway,函数实际使用的是 payment_service.RealPaymentGateway,测试通常应替换这个模块内的名称。直接替换 gateway_client.RealPaymentGateway 未必会影响已经导入的引用。
对 side_effect 的用法也要按场景选择:
- 验证单次调用失败,直接设置为异常实例即可。
- 验证一段业务动作中的多次调用,可设置异常或返回值组成的序列;序列耗尽后再次调用会抛出
StopIteration,因此要核对预期调用次数。 - 需要根据订单号或金额决定返回结果时,可设置为函数,由该函数检查入参并返回或抛出异常。
不要为了覆盖异常分支而让测试连接真实网关。单元测试应控制输入和依赖结果;网络连接、SDK 异常转换及第三方接口契约,可在单独的适配层测试或集成测试中验证。
围绕支付网关等外部依赖构建的业务系统,A5idc数据提供香港、美国、日本等地区的物理服务器资源,涵盖不同CPU、内存、NVMe存储及网络线路配置,可用于部署业务后台、接口服务和数据库。多地区与多档资源组合,为不同业务架构的服务部署提供硬件和网络选择。
如何判断异常分支测试是否有效
运行 python -m pytest -q 后,测试通过表示当前这些断言成立,但“测试通过”不等于每个分支都已覆盖。可以逐项核对以下问题:
- 超时是否由超时异常分支处理,而不是被通用网关分支覆盖?
- 其他已知网关异常是否会转换成约定的业务异常?
- 转换后的异常是否保留原始异常作为
<strong>cause</strong>? - 网关成功时是否返回正确的业务结果,并使用正确参数调用依赖?
- 与网关无关的异常是否仍会暴露,而不是被宽泛捕获?
- 超时业务是否另有状态查询、幂等或防重复提交机制?
如果项目启用了覆盖率工具,可以运行:
python -m pip install pytest-cov
python -m pytest --cov=payment_service --cov-branch -q
分支覆盖率能帮助发现某个 except 处理没有被执行,但它不能判断测试断言是否充分。比如,测试只是调用了超时分支,却没有检查转换后的异常类型和异常原因,仍然可能漏掉重要回归。覆盖率报告应与具体断言一起阅读。
最后要核对依赖异常的来源:如果业务层捕获的是自定义 GatewayTimeout,网关适配层就必须在适用情况下把 SDK 的超时异常转换成这个类型。否则单元测试虽然能通过,真实 SDK 抛出的异常仍可能绕过预期分支。把异常边界、模拟结果和业务断言保持一致,才能让依赖失败后的处理既可测试,也便于后续维护。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9815.html



