Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# Testing

structlog comes with tools for testing the logging behavior of your application.

If you need functionality similar to `unittest.TestCase.assertLogs()`, or you want to capture all logs for some other reason, you can use the `structlog.testing.capture_logs()` context manager:

    >>> from structlog import get_logger
    >>> from structlog.testing import capture_logs
    >>> with capture_logs() as cap_logs:
    ...    get_logger().bind(x="y").info("hello")
    >>> cap_logs
    [{'x': 'y', 'event': 'hello', 'log_level': 'info'}]

Note that inside the context manager all configured processors are disabled.

Note

`capture_logs()` relies on changing the configuration. If you have cache_logger_on_first_use enabled for performance, any cached loggers will not be affected, so it’s recommended you do not enable it during tests.

You can build your own helpers using `structlog.testing.LogCapture`. For example a pytest fixture to capture log output could look like this:

    @pytest.fixture(name="log_output")
    def fixture_log_output():
        return LogCapture()

    @pytest.fixture(autouse=True)
    def fixture_configure_structlog(log_output):
        structlog.configure(
            processors=[log_output]
        )

    def test_my_stuff(log_output):
        do_something()
        assert log_output.entries == [...]

You can also use `structlog.testing.CapturingLogger` (directly, or via `CapturingLoggerFactory` that always returns the same logger) that is more low-level and great for unit tests:

    >>> import structlog
    >>> cf = structlog.testing.CapturingLoggerFactory()
    >>> structlog.configure(logger_factory=cf, processors=[structlog.processors.JSONRenderer()])
    >>> log = get_logger()
    >>> log.info("test!")
    >>> cf.logger.calls
    [CapturedCall(method_name='info', args=('{"event": "test!"}',), kwargs={})]

Additionally structlog also ships with a logger that just returns whatever it gets passed into it: `structlog.testing.ReturnLogger`.

    >>> from structlog import ReturnLogger
    >>> ReturnLogger().info(42) == 42
    True
    >>> obj = ["hi"]
    >>> ReturnLogger().info(obj) is obj
    True
    >>> ReturnLogger().info("hello", when="again")
    (('hello',), {'when': 'again'})