Pythoncaplog获取错误日志详解

本文深入解析了 pytest 中 caplog fixture 的正确使用方法，揭示其默认仅捕获 WARNING 及以上日志的“隐藏规则”，强调必须显式调用 caplog.set_level() 才能可靠捕获 DEBUG/INFO 等低级别日志；同时指出应摒弃对易失、非结构化的 caplog.text 的依赖，转而利用 caplog.records 提供的完整 LogRecord 对象，通过 levelno、levelname、msg、args 和 getMessage() 等字段进行精准、健壮的日志断言——涵盖日志来源（record.name）、级别、格式化参数甚至异常上下文，避免因字符串匹配、大小写敏感或拼接混乱导致的脆弱测试，并提醒开发者警惕 conftest.py 中全局配置的 scope 陷阱，真正掌握日志测试中“该出现的没出现”与“不该出现的出现了”的关键分辨能力。

caplog fixture 默认只捕获 WARNING 及以上级别日志

pytest 的 caplog fixture 默认不会记录 DEBUG 或 INFO 级别的日志，哪怕你代码里写了 logging.debug("xxx")，caplog.records 里也看不到——这不是 bug，是 pytest 的默认配置。它模仿了生产环境日志级别习惯，但写测试时往往需要更细粒度的观察。

• 必须显式设置日志级别，比如在测试函数开头加 caplog.set_level(logging.DEBUG)
• 也可以在 pytest.ini 或 pyproject.toml 中全局配置：log_cli_level = DEBUG，但注意这会影响所有测试，可能掩盖真实问题
• 如果用 @pytest.mark.parametrize 多次运行同一测试，每次都要重新调用 set_level()，因为 caplog 是 function-scoped fixture，每次执行都是干净实例

怎么拿到完整日志信息流（含 levelno、levelname、msg、args）

caplog.records 返回的是 logging.LogRecord 实例列表，每个 record 都带原始结构化字段，不是拼好的字符串。很多人直接 print caplog.text 就以为“看到日志了”，其实丢掉了关键上下文。

• caplog.records[0].levelno 是整数（10=DEBUG, 20=INFO），比字符串判断更可靠
• caplog.records[0].levelname 是字符串（"DEBUG"），适合断言可读性
• caplog.records[0].msg 是原始格式字符串（如 "User %s logged in from %s"），不包含 .args 展开后的值
• 要检查最终输出内容，得用 caplog.records[0].getMessage()，它等价于 record.msg % record.args
• 别用 caplog.text 做精确匹配——它是所有日志按 \n 拼接的字符串，换行/空格不可控，且丢失 record 元数据

测试中 assert 日志输出时容易漏掉的三个条件

光看有没有某条日志远远不够。日志是否在正确时机触发、是否来自预期模块、是否带预期参数，都得验证。否则改个 logger = logging.getLogger(__name__) 到 getLogger("root") 就让测试失效。

• 检查 record.name 字段，确认来源 logger 名（比如 "myapp.auth" 而不是 "root"）
• 用 record.levelno == logging.ERROR 断言级别，避免字符串比较（"ERROR" vs "error" 或大小写敏感问题）
• 如果日志用了 lazy formatting（如 logger.info("user=%s", user_obj)），record.args 是元组，要检查 len(record.args) == 1 且 isinstance(record.args[0], User)，而不是硬 match 字符串

caplog 在 conftest.py 里复用时的 scope 陷阱

有人把 caplog.set_level(logging.DEBUG) 写进 conftest.py 的 pytest_configure，结果部分测试还是捕不到 INFO 日志——因为 caplog fixture 本身是 function-scoped，它的状态（比如当前 level）不会跨测试函数继承。

• 不能靠全局配置“一次设置，处处生效”；每个测试函数内必须显式调用 caplog.set_level(...)
• 如果想减少重复，可以封装一个 fixture：@pytest.fixture(autouse=True) + def set_caplog_level(caplog): caplog.set_level(logging.DEBUG)，但要注意 autouse 会影响所有测试，慎用
• 更稳妥的做法：在每个需要日志断言的测试函数第一行写 caplog.set_level(logging.DEBUG)，清晰、可控、无副作用

日志测试真正的难点不在捕获，而在区分“该出现的没出现”和“不该出现的出现了”。record 对象的字段越多，越容易写出脆弱断言——比如过度依赖 getMessage() 而忽略格式化失败场景。留心 args 和 exc_info 是否为空，比死盯 message 字符串有用得多。

今天关于《Pythoncaplog获取错误日志详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！