断言消息：自定义断言失败消息的艺术

断言失败时，你看到的是什么？

很多人只看到一行冰冷的「AssertionError」。然后呢？然后你得翻代码、查变量、猜逻辑。说实话，这太浪费时间了。

我个人习惯，每个断言都带上自定义消息。这不是锦上添花，这是刚需。你想想看，测试跑了几百条，突然挂了一条。如果消息里直接告诉你「用户年龄字段不能为负数，当前值: -5」，你一眼就知道问题在哪。省下的时间，够你喝杯咖啡了。

为什么需要自定义消息？

默认的断言消息，说白了就是告诉你「这里出错了」。但错在哪里？错得多离谱？它不说。

我在项目中遇到过一件事：一个支付系统的测试，断言金额相等。结果失败了，只显示「False is not true」。我花了半小时排查，最后发现是精度问题——3.0 和 3.00 在 Python 里不一样。如果当时我写了自定义消息，5 秒就能定位。

所以，自定义消息的核心价值就三点：

• 快速定位：直接告诉你哪个变量、什么值、期望是什么
• 上下文保留：失败时能看到当时的业务场景
• 团队协作：别人接手你的测试，一看就懂

消息格式化：让信息一目了然

光有消息还不够，格式得讲究。我见过有人写「a不等于b，a=xxx，b=yyy」，挤在一行里，看着就头疼。

我的做法是用 f-string 配合换行符，把信息拆开：

# 不推荐
assert result == expected, f"结果不匹配: {result} vs {expected}"

# 推荐
assert result == expected, (
    f"结果不匹配\n"
    f"  期望值: {expected}\n"
    f"  实际值: {result}\n"
    f"  差值: {result - expected}"
)

你看，这样一格式化，信息层次就出来了。哪行是期望，哪行是实际，一目了然。

嗯，这里要注意：消息里不要塞太多无关信息。比如把整个请求报文都打印出来，那就本末倒置了。只放关键变量就好。

动态消息生成：根据上下文自动组装

有时候，断言消息需要根据不同的输入动态生成。比如你写了一个通用的数据校验函数，断言失败时，消息里要包含具体的字段名和值。

我常用的方式有两种：

方式	适用场景	示例
f-string 直接嵌入	简单变量，字段固定	f"年龄 {age} 超出范围 [0, 150]"
函数生成消息	复杂逻辑，需要条件判断	build_error_msg(field, value, rules)

举个例子，我之前写过一个数据清洗工具，里面有个断言函数：

def assert_valid_record(record):
    for field, value in record.items():
        msg = (
            f"字段校验失败\n"
            f"  记录ID: {record.get('id', 'N/A')}\n"
            f"  字段名: {field}\n"
            f"  当前值: {value}\n"
            f"  期望: 非空且类型为 str"
        )
        assert isinstance(value, str) and value.strip(), msg

这样每条记录校验失败时，消息里都包含了记录ID、字段名和当前值。你想想看，如果数据有 10 万条，失败了一条，你能直接根据消息里的 ID 去查原始数据，多省事。

避坑指南：我踩过的几个坑

讲几个我亲身经历过的教训：

• 消息里不要包含敏感信息：我曾经在断言消息里打印了用户手机号，结果测试日志被传到 CI 系统，差点出事。密码、身份证号、 这些，千万别放进去。
• 消息不要太长：有人喜欢把整个堆栈都塞进消息里。结果控制台输出几万行，根本没法看。控制在 5 行以内，够用就行。
• 注意性能：如果断言消息里调用了复杂的字符串拼接或函数，在循环里会拖慢速度。我一般只在消息里放变量名和值，不做额外计算。

知识体系：一张图看懂断言消息

下面这张图，是我自己总结的断言消息设计思路。从「为什么需要」到「怎么实现」，再到「注意事项」，一条线串起来。

这张图把断言消息的设计拆成了三个维度。我个人建议，每次写断言前，先想想这三个问题：为什么需要这条消息？用什么方式生成？有没有踩坑？想清楚了再下笔。

好了，关于断言消息就聊这么多。记住一句话：好的断言消息，是测试代码的「说明书」。你写得越清楚，后面的人（包括未来的你）就越省心。