_pytest.capture module

per-test stdout/stderr capturing mechanism.

class CloseStdinType(value)

Bases: enum.Enum

An enumeration.

CLOSE_STDIN = 1

CLOSE_STDIN = <CloseStdinType.CLOSE_STDIN: 1>

Sentinel to close stdin.

pytest_addoption(parser)

for ... in pytest_load_initial_conftests(early_config: _pytest.config.Config)

_get_multicapture(method: _CaptureMethod) → MultiCapture

class CaptureManager(method: _CaptureMethod)

Bases: object

Capture plugin, manages that the appropriate capture method is enabled/disabled during collection and each test phase (setup, call, teardown). After each of those points, the captured output is obtained and attached to the collection/runtest report.

There are two levels of capture: * global: which is enabled by default and can be suppressed by the -s option. This is always enabled/disabled

during collection and each test phase.

• fixture: when a test function or one of its fixture depend on the capsys or capfd fixtures. In this case special handling is needed to ensure the fixtures take precedence over the global capture.

is_capturing()

is_globally_capturing()

start_global_capturing()

stop_global_capturing()

resume_global_capture()

suspend_global_capture(in_=False)

suspend(in_=False)

resume()

read_global_capture()

with _capturing_for_request(request: _pytest.fixtures.FixtureRequest) → Generator[CaptureFixture, None, None]

Context manager that creates a CaptureFixture instance for the given request, ensuring there is only a single one being requested at the same time.

This is used as a helper with capsys, capfd etc.

activate_fixture()

If the current item is using capsys or capfd, activate them so they take precedence over the global capture.

deactivate_fixture()

Deactivates the capsys or capfd fixture of this item, if any.

suspend_fixture()

resume_fixture()

with global_and_fixture_disabled()

Context manager to temporarily disable global and current fixture capturing.

with item_capture(when, item)

for ... in pytest_make_collect_report(collector)

for ... in pytest_runtest_setup(item)

for ... in pytest_runtest_call(item)

for ... in pytest_runtest_teardown(item)

pytest_keyboard_interrupt(excinfo)

pytest_internalerror(excinfo)

for ... in capsys(request)

Enable text capturing of writes to sys.stdout and sys.stderr.

The captured output is made available via capsys.readouterr() method calls, which return a (out, err) namedtuple. out and err will be text objects.

for ... in capsysbinary(request)

Enable bytes capturing of writes to sys.stdout and sys.stderr.

The captured output is made available via capsysbinary.readouterr() method calls, which return a (out, err) namedtuple. out and err will be bytes objects.

for ... in capfd(request)

Enable text capturing of writes to file descriptors 1 and 2.

The captured output is made available via capfd.readouterr() method calls, which return a (out, err) namedtuple. out and err will be text objects.

for ... in capfdbinary(request)

Enable bytes capturing of writes to file descriptors 1 and 2.

The captured output is made available via capfd.readouterr() method calls, which return a (out, err) namedtuple. out and err will be byte objects.

class CaptureFixture(captureclass, request)

Bases: object

Object returned by capsys(), capsysbinary(), capfd() and capfdbinary() fixtures.

_start()

close()

readouterr()

Read and return the captured output so far, resetting the internal buffer.

Returns

captured content as a namedtuple with out and err string attributes

_suspend()

Suspends this fixture’s own capturing temporarily.

_resume()

Resumes this fixture’s own capturing temporarily.

with disabled()

Temporarily disables capture while inside the ‘with’ block.

safe_text_dupfile(f, mode, default_encoding='UTF8')

return an open text file object that’s a duplicate of f on the FD-level if possible.

class EncodedFile(buffer: BinaryIO, encoding: str)

Bases: object

errors = 'strict'

write(s: str) → int

writelines(lines: Iterable[str]) → None

name

Ensure that file.name is a string.

mode

class CaptureResult(out, err)

Bases: tuple

_asdict()

Return a new dict which maps field names to their values.

_field_defaults = {}

_fields = ('out', 'err')

_fields_defaults = {}

classmethod _make(iterable)

Make a new CaptureResult object from a sequence or iterable

_replace(**kwds)

Return a new CaptureResult object replacing specified fields with new values

err

Alias for field number 1

out

Alias for field number 0

class MultiCapture(out=True, err=True, in_=True, Capture=None)

Bases: object

_state = None

_in_suspended = False

in_ = None

out = None

err = None

start_capturing()

pop_outerr_to_orig()

pop current snapshot out/err capture and flush to orig streams.

suspend_capturing(in_=False)

resume_capturing()

stop_capturing()

stop capturing and reset capturing streams

readouterr()

return snapshot unicode value of stdout/stderr capturings.

class NoCapture

Bases: object

EMPTY_BUFFER = None

start()

done()

suspend()

resume()

class FDCaptureBinary(targetfd, tmpfile=None)

Bases: object

Capture IO to/from a given os-level filedescriptor.

snap() produces bytes

EMPTY_BUFFER = b''

_state = None

_start()

Start capturing on targetfd using memorized tmpfile.

snap()

_done()

stop capturing, restore streams, return original capture file, seeked to position zero.

suspend()

resume()

writeorg(data)

write to original file descriptor.

class FDCapture(targetfd, tmpfile=None)

Bases: _pytest.capture.FDCaptureBinary

Capture IO to/from a given os-level filedescriptor.

snap() produces text

EMPTY_BUFFER = ''

snap()

class SysCaptureBinary(fd, tmpfile=None, stdin=<CloseStdinType.CLOSE_STDIN: 1>)

Bases: object

CLOSE_STDIN = 1

EMPTY_BUFFER = b''

_state = None

start()

snap()

done()

suspend()

resume()

writeorg(data: bytes) → None

class SysCapture(fd, tmpfile=None, stdin=<CloseStdinType.CLOSE_STDIN: 1>)

Bases: _pytest.capture.SysCaptureBinary

EMPTY_BUFFER = ''

snap()

writeorg(data: str) → None

class TeeSysCapture(fd, tmpfile=None)

Bases: _pytest.capture.SysCapture

class DontReadFromInput

Bases: object

encoding = None

read(*args)

readline(*args)

readlines(*args)

fileno()

isatty()

close()

buffer

_colorama_workaround()

Ensure colorama is imported so that it attaches to the correct stdio handles on Windows.

colorama uses the terminal on import time. So if something does the first import of colorama while I/O capture is active, colorama will fail in various ways.

_readline_workaround()

Ensure readline is imported so that it attaches to the correct stdio handles on Windows.

Pdb uses readline support where available–when not running from the Python prompt, the readline module is not imported until running the pdb REPL. If running pytest with the –pdb option this means the readline module is not imported until after I/O capture has been started.

This is a problem for pyreadline, which is often used to implement readline support on Windows, as it does not attach to the correct handles for stdout and/or stdin if they have been redirected by the FDCapture mechanism. This workaround ensures that readline is imported before I/O capture is setup so that it can attach to the actual stdin/out for the console.

See https://github.com/pytest-dev/pytest/pull/1281

_py36_windowsconsoleio_workaround(stream)

Python 3.6 implemented unicode console handling for Windows. This works by reading/writing to the raw console handle using {Read,Write}ConsoleW.

The problem is that we are going to dup2 over the stdio file descriptors when doing FDCapture and this will CloseHandle the handles used by Python to write to the console. Though there is still some weirdness and the console handle seems to only be closed randomly and not on the first call to CloseHandle, or maybe it gets reopened with the same handle value when we suspend capturing.

The workaround in this case will reopen stdio with a different fd which also means a different handle by replicating the logic in “Py_lifecycle.c:initstdio/create_stdio”.

Parameters

stream – in practice sys.stdout or sys.stderr, but given here as parameter for unittesting purposes.

See https://github.com/pytest-dev/py/issues/103