
Pytest 的 caplog fixture 依赖于对根日志器的无侵入式接管,若在测试中调用 logging.config.dictConfig() 等配置操作,会清空 pytest 自动添加的捕获处理器,导致日志无法被捕获。
pytest 的 caplog fixture 依赖于对根日志器的无侵入式接管,若在测试中调用 `logging.config.dictconfig()` 等配置操作,会清空 pytest 自动添加的捕获处理器,导致日志无法被捕获。
在 Pytest 中,caplog 是一个强大且常用的内置 fixture,用于在单元测试中断言日志输出行为(如消息内容、日志级别、记录数量等)。其底层原理是:在测试开始前,pytest 自动向根日志器(root logger)添加一个专用的 LogCaptureHandler;测试结束后自动移除。这意味着 caplog 的正常工作高度依赖于日志系统配置的“稳定性”——任何对根日志器的重置性配置(例如 logging.basicConfig()、logging.config.dictConfig() 或 logging.config.fileConfig())都会覆盖或清除该捕获处理器,造成 caplog.records 和 caplog.messages 为空。
如问题示例所示,尽管日志成功输出到控制台(说明 logger 本身工作正常),但 caplog.messages 为 [],根本原因正是 logging.config.dictConfig(LOGGING_CONFIG) 完全重置了整个日志系统,包括 pytest 注入的捕获 handler。
✅ 正确做法是:避免在测试函数内进行日志配置。应让 pytest 全权管理日志捕获基础设施,仅通过 caplog.at_level() 控制捕获的最低级别,并直接使用标准 logging.getLogger() 获取 logger 实例:
import logging
def test_logging(caplog):
logger = logging.getLogger("root_module.sub1.sub2")
with caplog.at_level(logging.DEBUG):
logger.debug("? DEBUG msg")
logger.info("? INFO msg")
logger.warning("⚠️ WARNING msg")
logger.error("❌ ERROR msg")
logger.critical("? CRITICAL msg")
# ✅ 此时 caplog.records 已包含全部 5 条 LogRecord 对象
assert len(caplog.records) == 5
assert caplog.records[0].levelname == "DEBUG"
assert "CRITICAL" in caplog.text # 或使用 caplog.messages 检查文本内容
⚠️ 补充注意事项:
- 若被测代码(SUT)内部调用了日志配置(如模块级
dictConfig),应在测试中用unittest.mock.patch将其打桩(patch); - 如需全局统一日志格式(如 CI 环境),应通过
pytest.ini或pyproject.toml的log_cli_level/log_file_level配置,而非在测试中动态配置; -
caplog.at_level()仅影响当前with块内的日志捕获级别,不影响 logger 自身的setLevel(),推荐优先使用它而非修改 logger 级别; - 调试时可启用
pytest --log-cli-level=DEBUG查看实时日志流,辅助定位捕获失败原因。
总之,caplog 不是“日志配置工具”,而是“日志捕获工具”。尊重其设计契约——不干扰根日志器状态——是确保日志断言可靠性的关键。










