为Python业务代码编写单元测试,怎样覆盖依赖调用失败后的异常处理分支?

发布人:A5数据发布时间:2026-11-16 13:38阅读量:15

依赖调用失败后的异常分支,单元测试要验证的不只是“抛出了异常”,还要确认业务代码是否把依赖异常转换成合适的业务异常、是否保留了原始异常,以及成功路径和非预期程序错误有没有被误处理。下面用一个支付网关调用说明如何实现:在业务方法中注入网关依赖,通过 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 后,测试通过表示当前这些断言成立,但“测试通过”不等于每个分支都已覆盖。可以逐项核对以下问题:

  1. 超时是否由超时异常分支处理,而不是被通用网关分支覆盖?
  2. 其他已知网关异常是否会转换成约定的业务异常?
  3. 转换后的异常是否保留原始异常作为 <strong>cause</strong>?
  4. 网关成功时是否返回正确的业务结果,并使用正确参数调用依赖?
  5. 与网关无关的异常是否仍会暴露,而不是被宽泛捕获?
  6. 超时业务是否另有状态查询、幂等或防重复提交机制?

如果项目启用了覆盖率工具,可以运行:

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

相关推荐