
Capturing of the stdout/stderr output
*************************************


Default stdout/stderr/stdin capturing behaviour
===============================================

During test execution any output sent to "stdout" and "stderr" is
captured.  If a test or a setup method fails its according captured
output will usually be shown along with the failure traceback.

In addition, "stdin" is set to a "null" object which will fail on
attempts to read from it because it is rarely desired to wait for
interactive input when running automated tests.

By default capturing is done by intercepting writes to low level file
descriptors.  This allows to capture output from simple print
statements as well as output from a subprocess started by a test.


Setting capturing methods or disabling capturing
================================================

There are two ways in which "py.test" can perform capturing:

* file descriptor (FD) level capturing (default): All writes going to
  the operating system file descriptors 1 and 2 will be captured.

* "sys" level capturing: Only writes to Python files "sys.stdout" and
  "sys.stderr" will be captured.  No capturing of writes to
  filedescriptors is performed.

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  # also point filedescriptors 1 and 2 to temp file


Using print statements for debugging
====================================

One primary benefit of the default capturing of stdout/stderr output
is that you can use print statements for debugging:

   # content of test_module.py

   def setup_function(function):
       print ("setting up %s" % function)

   def test_func1():
       assert True

   def test_func2():
       assert False

and running this module will show you precisely the output of the
failing function and hide the other one:

   $ py.test
   =========================== test session starts ============================
   platform linux2 -- Python 2.7.3 -- pytest-2.3.5
   collected 2 items

   test_module.py .F

   ================================= FAILURES =================================
   ________________________________ test_func2 ________________________________

       def test_func2():
   >       assert False
   E       assert False

   test_module.py:9: AssertionError
   ----------------------------- Captured stdout ------------------------------
   setting up <function test_func2 at 0x2d79f50>
   ==================== 1 failed, 1 passed in 0.01 seconds ====================


Accessing captured output from a test function
==============================================

The *Fixtures as Function arguments (funcargs)* allows test function a
very easy way to access the captured output by simply using the names
"capsys" or "capfd" in the test function signature.  Here is an
example test function that performs some output related checks:

   def test_myoutput(capsys): # or use "capfd" for fd-level
       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.  Using "capsys" this way frees your test
from having to care about setting/resetting output streams and also
interacts well with py.test's own per-test capturing.

If you want to capture on "fd" level you can use the "capfd" function
argument which offers the exact same interface.
