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