133 lines
4.3 KiB
Plaintext
133 lines
4.3 KiB
Plaintext
|
|
configurable per-test stdout/stderr capturing mechanisms.
|
|
=========================================================
|
|
|
|
|
|
.. contents::
|
|
:local:
|
|
|
|
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.
|
|
|
|
.. _`funcarg example`:
|
|
|
|
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:
|
|
|
|
.. sourcecode:: python
|
|
|
|
def test_myoutput(capsys):
|
|
print ("hello")
|
|
sys.stderr.write("world\n")
|
|
out, err = capsys.readouterr()
|
|
assert out == "hello\n"
|
|
assert err == "world\n"
|
|
print "next"
|
|
out, err = capsys.readouterr()
|
|
assert out == "next\n"
|
|
|
|
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.
|
|
|
|
.. _`capsys funcarg`:
|
|
|
|
|
|
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.
|
|
|
|
.. _`capfd funcarg`:
|
|
|
|
|
|
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. If the underlying
|
|
platform does not have ``os.dup`` (e.g. Jython) tests using
|
|
this funcarg will automatically skip.
|
|
|
|
command line options
|
|
--------------------
|
|
|
|
|
|
``--capture=method``
|
|
per-test capturing method: one of 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`_.
|
|
|
|
.. include:: links.txt
|