pytest-structlog

结构化日志断言。 pytest + structlog = pytest-structlog.

安装

$ pip install pytest-structlog

使用

固定名称为 log。它有两个感兴趣的属性：log.events 是捕获的日志调用的事件列表，而 log.has 是一个辅助函数，用于断言在预期的上下文中已记录单个事件。

假设你有一个库模块，your_lib，它使用 structlog

# your_lib.py
from structlog import get_logger

logger = get_logger()

def spline_reticulator():
    logger.info("reticulating splines")
    for i in range(3):
        logger.debug("processing", spline=i)
    logger.info("reticulated splines", n_splines=3)

然后你的测试套件可能使用如下所示的断言

# test_your_lib.py
from your_lib import spline_reticulator
import pytest_structlog

def test_spline_reticulator(log: pytest_structlog.StructuredLogCapture):
    assert len(log.events) == 0
    spline_reticulator()
    assert len(log.events) == 5

    # can assert on the event only
    assert log.has("reticulating splines")

    # can assert with subcontext
    assert log.has("reticulated splines")
    assert log.has("reticulated splines", n_splines=3)
    assert log.has("reticulated splines", n_splines=3, level="info")

    # but not incorrect context
    assert not log.has("reticulated splines", n_splines=42)
    assert not log.has("reticulated splines", key="bogus")

    # can assert with the event dicts directly
    assert log.events == [
        {"event": "reticulating splines", "level": "info"},
        {"event": "processing", "level": "debug", "spline": 0},
        {"event": "processing", "level": "debug", "spline": 1},
        {"event": "processing", "level": "debug", "spline": 2},
        {"event": "reticulated splines", "level": "info", "n_splines": 3},
    ]

    # can use friendly factory methods for the events to assert on
    assert log.events == [
        log.info("reticulating splines"),
        log.debug("processing", spline=0),
        log.debug("processing", spline=1),
        log.debug("processing", spline=2),
        log.info("reticulated splines", n_splines=3),
    ]

    # can use membership to check for a single event's data
    assert {"event": "reticulating splines", "level": "info"} in log.events

    # can use >= to specify only the events you're interested in
    assert log.events >= [
        {"event": "processing", "level": "debug", "spline": 0},
        {"event": "processing", "level": "debug", "spline": 2},
    ]

    # or put the comparison the other way around if you prefer
    assert [
        {"event": "processing", "level": "debug", "spline": 0},
        {"event": "processing", "level": "debug", "spline": 2},
    ] <= log.events

    # note: comparisons are order sensitive!
    assert not [
        {"event": "processing", "level": "debug", "spline": 2},
        {"event": "processing", "level": "debug", "spline": 0},
    ] <= log.events

高级配置

默认情况下，pytest-structlog 尝试削弱任何现有的 structlog 配置，并为测试目的设置一系列处理器。有时可能需要更多的控制，例如，如果正在测试的代码使用自定义处理器，即使在测试期间也应该保留这些处理器。

为此，插件提供了一些选项来覆盖测试处理器

$ pytest --help | grep structlog --after=2
pytest-structlog:
  --structlog-keep=PROCESSOR_NAME
                        Processors to keep if configured (may be specified
                        multiple times).
  --structlog-evict=PROCESSOR_NAME
                        Processors to evict if configured (may be specified
                        multiple times).
...
  structlog_keep (args):
                        Processors to keep if configured (list of names)
  structlog_evict (args):
                        Processors to evict if configured (list of names)

通过以下方式指示在测试期间应保留某些特定的处理器

pytest --structlog-keep my_processor1 --structlog-keep MyProcessor2

或者直接在配置文件中写入，例如在 pyproject.toml 中

[tool.pytest.ini_options]
structlog_keep = ["my_processor1", "MyProcessor2"]

有时，与其列出要保留的处理器列表，不如列出在测试期间要 排除 的处理器。在这种情况下，您可以指定一个驱逐列表

[tool.pytest.ini_options]
structlog_evict = ["TimeStamper", "JSONRender"]

您只能使用 "保留" 或 "驱逐" 模式。指定两者是错误的。

要完全控制测试中应使用的处理器，最佳方式是在 conftest.py 文件中直接添加 structlog.configure() 调用，并在运行 pytest 时使用 --structlog-explicit（或设置 structlog_explicit = true）以完全禁用自动处理器选择。

使用pytest -v或pytest -vv，您可以查看更多关于pytest-structlog在测试启动期间包含或排除哪些处理器的详细信息。pytest-structlog自己设置的报告也可以通过指定--structlog-settings-report always/never（命令行）或structlog_settings_report（ini）来显式启用/禁用，而与详细程度无关。