pytest_capture plugin
=====================

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