Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 38 ยท Tests and Assertions

Testing Warnings, Output and Logs

Test that code emits the right warnings with pytest.warns, capture printed output with capsys, check log records with caplog, and turn warnings into errors.

Not everything your code does is a return value. A function may print a report, write a log line, or warn that a feature is deprecated. These side effects are part of the contract, and pytest has built-in helpers to check them: pytest.warns for warnings, and two ready-made fixtures called capsys and caplog for printed text and logging.

A fixture is something pytest hands to your test when you list its name as a parameter. You will learn to write your own in the Fixtures chapter; for now, just ask for capsys or caplog by name and use them.

Testing warnings with pytest.warns

Libraries use warnings.warn(...) to tell callers that something is deprecated or risky without stopping the program. To test it, wrap the call:

Python pytest.warns

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The structure mirrors pytest.raises: the test passes if at least one matching warning is emitted in the block. match is again a regular expression. To inspect the warning objects, bind the context manager:

Python
with pytest.warns(UserWarning) as record:
    do_something()
assert len(record) == 1
assert "disk almost full" in str(record[0].message)

Making sure nothing warns

Surprisingly useful: assert that code runs without emitting warnings. Use the standard library's warnings module inside the test:

Python
import warnings

def test_clean_call():
    with warnings.catch_warnings():
        warnings.simplefilter("error")   # any warning becomes an exception
        new_api()

Or turn warnings into failures for the whole suite in the config file, so deprecations never pile up unnoticed:

INI
[pytest]
filterwarnings =
    error
    ignore::DeprecationWarning:some_old_library.*

The filterwarnings setting uses the same syntax as Python's -W option. error makes every warning fail the test; the ignore line makes an exception for noise you cannot fix. You can also apply a filter to a single test with @pytest.mark.filterwarnings("ignore:old_api").

Python filterwarnings mark

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

By default pytest collects warnings and shows a summary at the end ("warnings summary") instead of letting them scroll by. The third test fails because the warning became an exception.

Capturing printed output: capsys

If a function prints instead of returning, the capsys fixture lets you read what it printed. Call capsys.readouterr(); it returns an object with .out and .err strings and resets the buffers.

Python capsys captures stdout and stderr

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notes:

  • print adds a newline, so compare with "...\n" or call .strip() / use in.
  • readouterr() can be called several times; each call returns only what was printed since the previous call.
  • capsys captures at the Python level. Use capfd to capture at the file-descriptor level, which also catches output from C extensions and subprocesses. Their binary versions are capsysbinary and capfdbinary.

Checking log messages: caplog

The logging module sends records to handlers, not to stdout. The caplog fixture installs a handler for the duration of a test and exposes what was logged:

Python caplog

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What caplog offers:

Attribute Meaning
caplog.text all captured output as one formatted string
caplog.records list of LogRecord objects
caplog.record_tuples list of (logger_name, level, message)
caplog.messages list of formatted messages
caplog.set_level(level, logger=None) change the level for the rest of the test
caplog.at_level(level) context manager that changes the level temporarily
caplog.clear() forget what was captured so far

Remember that loggers only emit records at or above their level, and the root logger defaults to WARNING. If an info message does not appear, set the level first.

Which tool for which side effect?

flowchart TD
    A["What do I want to check?"] --> B{"Kind of output"}
    B -->|"print / sys.stdout"| C["capsys"]
    B -->|"subprocess or C code output"| D["capfd"]
    B -->|"logging records"| E["caplog"]
    B -->|"warnings.warn"| F["pytest.warns"]
    B -->|"raised error"| G["pytest.raises"]

Pick the narrowest tool: each one checks one kind of side effect.

A word of caution

Testing printed output makes tests brittle: any change in wording or spacing breaks them. Prefer designs where the function returns data and a thin outer layer prints it. Then you test the return value precisely and keep one small test for the printing. The same applies to logs: assert the level and the key fact, not every character.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which tool checks that a function calls warnings.warn(..., DeprecationWarning)?

    pytest.warns records warnings in its block and fails if no matching warning was emitted. pytest.raises is for exceptions.
  2. 2. What does capsys.readouterr() return?

    readouterr() returns the captured stdout and stderr and resets the buffers.
  3. 3. An info log message is missing from caplog.text. What is the most likely cause?

    Records below the effective logger level are never created, so set the level to INFO or lower.
  4. 4. How do you make every warning fail the whole test suite?

    The filterwarnings ini option accepts Python warning filter syntax, and error turns each warning into an exception.

Summary

  • pytest.warns(Category, match=...) asserts that a warning is emitted.
  • filterwarnings (ini option or mark) can ignore warnings or turn them into errors.
  • capsys and capfd capture printed output; readouterr() returns .out and .err.
  • caplog exposes log text and records; set the level so the messages you expect are created.
  • Prefer returning values over printing so that tests stay precise.

Next: Organizing Tests with Classes