断言消息：自定义错误消息的艺术

断言失败时，光知道「哪行代码出了问题」远远不够。我见过太多团队，断言一触发，开发人员得翻半天源码才能猜出问题在哪。说白了，断言消息就是你的「求救信号」——信号越清晰，救你的人越快。

为什么需要自定义错误消息？

默认的断言消息长这样：

AssertionError

嗯，就一个异常类型。你想想看，如果测试用例跑了几百个，突然蹦出这么一行，你根本不知道是哪个断言炸了。我在项目中遇到过这种情况，排查了整整一下午，最后发现只是某个边界值没处理好。

自定义消息能帮你做到三件事：

快速定位：一眼看出是哪个断言失败
理解上下文：知道当时在测什么场景
记录现场数据：保留失败时的关键变量值

核心原则：断言消息应该让一个不了解代码的人，也能明白发生了什么问题。

消息格式化：把数据塞进消息里

光写「值不匹配」太敷衍了。你得把实际值和期望值都放进去。我习惯用 f-string 来做这件事：

def test_user_age():
    user_age = get_user_age("张三")
    expected_age = 25
    
    # 不好的写法
    assert user_age == expected_age, "年龄不匹配"
    
    # 好的写法
    assert user_age == expected_age, f"用户年龄不匹配：期望 {expected_age}，实际 {user_age}"

你看，第二种写法一跑出来，问题一目了然。我曾经接手过一个项目，里面全是第一种写法，每次断言失败都得加断点调试，效率低得让人抓狂。

格式化时要注意几个细节：

数值类型：保留足够精度，但别太多。比如浮点数保留两位小数就够了
字符串类型：截断过长的字符串，避免消息刷屏
集合类型：显示元素个数，必要时才展开内容

def test_large_list():
    data = list(range(1000))
    expected = list(range(1000))
    
    # 好的做法：显示长度
    assert data == expected, f"列表不匹配：长度 {len(data)} vs {len(expected)}"
    
    # 如果确实需要看差异，只显示前几个
    if data != expected:
        diff_indices = [i for i in range(len(data)) if data[i] != expected[i]]
        assert False, f"列表在索引 {diff_indices[:5]} 处不匹配"

消息的最佳实践：我踩过的坑

这些年写断言消息，我总结了几条铁律。每一条背后都有血泪教训。

1. 消息要具体，别写废话

我曾经见过这样的断言消息：

assert result is not None, "结果不应该为空"

废话！断言本身已经说明「结果不应该为空」了。你应该告诉别人：

assert result is not None, f"查询用户ID={user_id} 时返回了空结果，请检查数据库是否存在该用户"

2. 包含关键上下文

断言失败时，你往往需要知道「在什么条件下」失败的。我习惯把输入参数也带上：

def test_calculate_discount(price, user_level):
    discount = calculate_discount(price, user_level)
    expected = price * 0.8 if user_level == "VIP" else price
    
    assert discount == expected, (
        f"折扣计算异常：价格={price}，用户等级={user_level}，"
        f"期望折扣={expected}，实际折扣={discount}"
    )

3. 别在消息里做复杂计算

断言消息只在失败时才会被求值，但如果你在里面做了耗时操作，每次断言都会执行。我踩过这个坑：

# 错误示范：每次断言都执行了昂贵的查询
assert user_count == expected, f"用户数不匹配，当前数据库用户：{fetch_all_users_from_db()}"

# 正确做法：只记录关键信息
assert user_count == expected, f"用户数不匹配：期望 {expected}，实际 {user_count}"

4. 统一消息格式

团队协作时，统一的消息格式能省很多事。我建议用这样的模板：

场景	消息模板	示例
值相等	期望 {expected}，实际 {actual}	期望 25，实际 30
值非空	{变量名} 不应为空，当前值：{value}	user_name 不应为空，当前值：None
布尔条件	条件 {condition} 应为真，当前输入：{inputs}	条件 is_active 应为真，当前输入：user_id=123
异常抛出	期望抛出 {exception_type}，实际返回 {return_value}	期望抛出 ValueError，实际返回 None

小技巧：我习惯在项目里定义一个断言工具函数，统一消息格式。这样大家写起来省事，排查起来也快。

def assert_with_context(condition, message, **context):
    """带上下文的断言工具"""
    if not condition:
        context_str = ", ".join(f"{k}={v}" for k, v in context.items())
        full_message = f"{message} | 上下文：{context_str}"
        raise AssertionError(full_message)

# 使用示例
assert_with_context(
    user.age == 25,
    "用户年龄不匹配",
    user_id=user.id,
    user_name=user.name,
    expected_age=25,
    actual_age=user.age
)

避坑指南：我曾经犯过的错

我曾经在消息里直接拼接用户输入，结果引发了敏感信息泄露。比如：

# 危险！用户密码被记录到了日志里
assert login_success, f"用户 {username} 使用密码 {password} 登录失败"

后来我加了一条规则：断言消息里永远不要记录敏感信息。密码、、身份证号这些，要么用掩码处理，要么干脆不写。

还有一次，我在消息里用了中文标点，结果在 CI 日志里显示成了乱码。从那以后，我统一用英文标点，省心。

警告：断言消息不要包含动态生成的、不可控的内容。比如从外部 API 返回的完整响应体，万一包含特殊字符，可能导致日志解析失败。

知识体系总览

下面这张图概括了断言消息的核心要点，我把它放在这里方便你回顾：

嗯，关于断言消息就聊这么多。记住一条：好的断言消息，能让调试时间缩短一半。下次写断言时，多花十秒钟把消息写清楚，后面能省下几个小时。

可可精品资料库

📚 课程目录

断言消息：自定义错误消息的艺术

为什么需要自定义错误消息？

消息格式化：把数据塞进消息里

消息的最佳实践：我踩过的坑

1. 消息要具体，别写废话

2. 包含关键上下文

3. 别在消息里做复杂计算

4. 统一消息格式

避坑指南：我曾经犯过的错

知识体系总览