1 2.. _`captures`: 3 4Capturing of the stdout/stderr output 5========================================================= 6 7Default stdout/stderr/stdin capturing behaviour 8--------------------------------------------------------- 9 10During test execution any output sent to ``stdout`` and ``stderr`` is 11captured. If a test or a setup method fails its according captured 12output will usually be shown along with the failure traceback. (this 13behavior can be configured by the ``--show-capture`` command-line option). 14 15In addition, ``stdin`` is set to a "null" object which will 16fail on attempts to read from it because it is rarely desired 17to wait for interactive input when running automated tests. 18 19By default capturing is done by intercepting writes to low level 20file descriptors. This allows to capture output from simple 21print statements as well as output from a subprocess started by 22a test. 23 24Setting capturing methods or disabling capturing 25------------------------------------------------- 26 27There are two ways in which ``pytest`` can perform capturing: 28 29* file descriptor (FD) level capturing (default): All writes going to the 30 operating system file descriptors 1 and 2 will be captured. 31 32* ``sys`` level capturing: Only writes to Python files ``sys.stdout`` 33 and ``sys.stderr`` will be captured. No capturing of writes to 34 filedescriptors is performed. 35 36.. _`disable capturing`: 37 38You can influence output capturing mechanisms from the command line:: 39 40 pytest -s # disable all capturing 41 pytest --capture=sys # replace sys.stdout/stderr with in-mem files 42 pytest --capture=fd # also point filedescriptors 1 and 2 to temp file 43 44.. _printdebugging: 45 46Using print statements for debugging 47--------------------------------------------------- 48 49One primary benefit of the default capturing of stdout/stderr output 50is that you can use print statements for debugging:: 51 52 # content of test_module.py 53 54 def setup_function(function): 55 print ("setting up %s" % function) 56 57 def test_func1(): 58 assert True 59 60 def test_func2(): 61 assert False 62 63and running this module will show you precisely the output 64of the failing function and hide the other one:: 65 66 $ pytest 67 =========================== test session starts ============================ 68 platform linux -- Python 3.x.y, pytest-3.x.y, py-1.x.y, pluggy-0.x.y 69 rootdir: $REGENDOC_TMPDIR, inifile: 70 collected 2 items 71 72 test_module.py .F [100%] 73 74 ================================= FAILURES ================================= 75 ________________________________ test_func2 ________________________________ 76 77 def test_func2(): 78 > assert False 79 E assert False 80 81 test_module.py:9: AssertionError 82 -------------------------- Captured stdout setup --------------------------- 83 setting up <function test_func2 at 0xdeadbeef> 84 ==================== 1 failed, 1 passed in 0.12 seconds ==================== 85 86Accessing captured output from a test function 87--------------------------------------------------- 88 89The ``capsys``, ``capsysbinary``, ``capfd``, and ``capfdbinary`` fixtures 90allow access to stdout/stderr output created during test execution. Here is 91an example test function that performs some output related checks: 92 93.. code-block:: python 94 95 def test_myoutput(capsys): # or use "capfd" for fd-level 96 print("hello") 97 sys.stderr.write("world\n") 98 captured = capsys.readouterr() 99 assert captured.out == "hello\n" 100 assert captured.err == "world\n" 101 print("next") 102 captured = capsys.readouterr() 103 assert captured.out == "next\n" 104 105The ``readouterr()`` call snapshots the output so far - 106and capturing will be continued. After the test 107function finishes the original streams will 108be restored. Using ``capsys`` this way frees your 109test from having to care about setting/resetting 110output streams and also interacts well with pytest's 111own per-test capturing. 112 113If you want to capture on filedescriptor level you can use 114the ``capfd`` fixture which offers the exact 115same interface but allows to also capture output from 116libraries or subprocesses that directly write to operating 117system level output streams (FD1 and FD2). 118 119.. versionadded:: 3.3 120 121The return value from ``readouterr`` changed to a ``namedtuple`` with two attributes, ``out`` and ``err``. 122 123.. versionadded:: 3.3 124 125If the code under test writes non-textual data, you can capture this using 126the ``capsysbinary`` fixture which instead returns ``bytes`` from 127the ``readouterr`` method. The ``capfsysbinary`` fixture is currently only 128available in python 3. 129 130 131.. versionadded:: 3.3 132 133If the code under test writes non-textual data, you can capture this using 134the ``capfdbinary`` fixture which instead returns ``bytes`` from 135the ``readouterr`` method. The ``capfdbinary`` fixture operates on the 136filedescriptor level. 137 138 139.. versionadded:: 3.0 140 141To temporarily disable capture within a test, both ``capsys`` 142and ``capfd`` have a ``disabled()`` method that can be used 143as a context manager, disabling capture inside the ``with`` block: 144 145.. code-block:: python 146 147 def test_disabling_capturing(capsys): 148 print("this output is captured") 149 with capsys.disabled(): 150 print("output not captured, going directly to sys.stdout") 151 print("this output is also captured") 152 153.. include:: links.inc 154