pytest_capture plugin

configurable per-test stdout/stderr capturing mechanisms.

This plugin captures stdout/stderr output for each test separately. In case of test failures this captured output is shown grouped togtther with the test.

The plugin also provides test function arguments that help to assert stdout/stderr output from within your tests, see the funcarg example.

Capturing of input/output streams during tests

By default sys.stdout and sys.stderr are substituted with temporary streams during the execution of tests and setup/teardown code. During the whole testing process it will re-use the same temporary streams allowing to play well with the logging module which easily takes ownership on these streams.

Also, 'sys.stdin' is substituted with a file-like "null" object that does not return any values. This is to immediately error out on tests that wait on reading something from stdin.

You can influence output capturing mechanisms from the command line:

py.test -s            # disable all capturing
py.test --capture=sys # replace sys.stdout/stderr with in-mem files
py.test --capture=fd  # point filedescriptors 1 and 2 to temp file

If you set capturing values in a conftest file like this:

# conftest.py
option_capture = 'fd'

then all tests in that directory will execute with "fd" style capturing.

sys-level capturing

Capturing on 'sys' level means that sys.stdout and sys.stderr will be replaced with in-memory files (py.io.TextIO to be precise) that capture writes and decode non-unicode strings to a unicode object (using a default, usually, UTF-8, encoding).

FD-level capturing and subprocesses

The fd based method means that writes going to system level files based on the standard file descriptors will be captured, for example writes such as os.write(1, 'hello') will be captured properly. Capturing on fd-level will include output generated from any subprocesses created during a test.

Example Usage of the capturing Function arguments

You can use the capsys funcarg and capfd funcarg to capture writes to stdout and stderr streams. Using the funcargs frees your test from having to care about setting/resetting the old streams and also interacts well with py.test's own per-test capturing. Here is an example test function:

The readouterr() call snapshots the output so far - and capturing will be continued. After the test function finishes the original streams will be restored. If you want to capture on the filedescriptor level you can use the capfd function argument which offers the same interface.

the 'capsys' test function argument

captures writes to sys.stdout/sys.stderr and makes them available successively via a capsys.readouterr() method which returns a (out, err) tuple of captured snapshot strings.

the 'capfd' test function argument

captures writes to file descriptors 1 and 2 and makes snapshotted (out, err) string tuples available via the capsys.readouterr() method.

command line options

--capture=method
set capturing method during tests: fd (default)|sys|no.
-s
shortcut for --capture=no.

Start improving this plugin in 30 seconds

  1. Download pytest_capture.py plugin source code
  2. put it somewhere as pytest_capture.py into your import path
  3. a subsequent py.test run will use your local version

Checkout customize, other plugins or get in contact.