From 749288dcb62bb242ba454ec956ad2ce2ad93b54b Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Thu, 8 Feb 2018 19:57:26 -0200 Subject: [PATCH] Add reference docs to cache and capture fixtures --- _pytest/capture.py | 18 ++++-- _pytest/fixtures.py | 2 +- doc/en/cache.rst | 21 +------ doc/en/reference.rst | 138 ++++++++++++++++++++++++++++++++++++++++++- 4 files changed, 153 insertions(+), 26 deletions(-) diff --git a/_pytest/capture.py b/_pytest/capture.py index 36658acce..5171358ef 100644 --- a/_pytest/capture.py +++ b/_pytest/capture.py @@ -197,9 +197,9 @@ def _ensure_only_one_capture_fixture(request, name): @pytest.fixture def capsys(request): - """Enable capturing of writes to sys.stdout/sys.stderr and make + """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make captured output available via ``capsys.readouterr()`` method calls - which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` + which return a ``(out, err)`` namedtuple. ``out`` and ``err`` will be ``text`` objects. """ _ensure_only_one_capture_fixture(request, 'capsys') @@ -209,7 +209,7 @@ def capsys(request): @pytest.fixture def capsysbinary(request): - """Enable capturing of writes to sys.stdout/sys.stderr and make + """Enable capturing of writes to ``sys.stdout`` and ``sys.stderr`` and make captured output available via ``capsys.readouterr()`` method calls which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``bytes`` objects. @@ -225,7 +225,7 @@ def capsysbinary(request): @pytest.fixture def capfd(request): - """Enable capturing of writes to file descriptors 1 and 2 and make + """Enable capturing of writes to file descriptors ``1`` and ``2`` and make captured output available via ``capfd.readouterr()`` method calls which return a ``(out, err)`` tuple. ``out`` and ``err`` will be ``text`` objects. @@ -272,6 +272,10 @@ def _install_capture_fixture_on_item(request, capture_class): class CaptureFixture(object): + """ + Object returned by :py:func:`capsys`, :py:func:`capsysbinary`, :py:func:`capfd` and :py:func:`capfdbinary` + fixtures. + """ def __init__(self, captureclass, request): self.captureclass = captureclass self.request = request @@ -288,6 +292,11 @@ class CaptureFixture(object): cap.stop_capturing() def readouterr(self): + """Read and return the captured output so far. + + :rtype: Tuple[str, str] + :return: captured content as a pair of (stdout, stdout) strings + """ try: return self._capture.readouterr() except AttributeError: @@ -295,6 +304,7 @@ class CaptureFixture(object): @contextlib.contextmanager def disabled(self): + """Temporarily disables capture while inside the 'with' block.""" self._capture.suspend_capturing() capmanager = self.request.config.pluginmanager.getplugin('capturemanager') capmanager.suspend_global_capture(item=None, in_=False) diff --git a/_pytest/fixtures.py b/_pytest/fixtures.py index f9d0ef572..955a112b1 100644 --- a/_pytest/fixtures.py +++ b/_pytest/fixtures.py @@ -858,7 +858,7 @@ class FixtureFunctionMarker(object): def fixture(scope="function", params=None, autouse=False, ids=None, name=None): - """ (return a) decorator to mark a fixture factory function. + """Decorator to mark a fixture factory function. This decorator can be used (with or without parameters) to define a fixture function. The name of the fixture function can later be diff --git a/doc/en/cache.rst b/doc/en/cache.rst index e3423e95b..81ef38088 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -212,7 +212,7 @@ the cache and this will be quick:: test_caching.py:14: AssertionError 1 failed in 0.12 seconds -See the `cache-api`_ for more details. +See the :ref:`cache-api` for more details. Inspecting Cache content @@ -247,22 +247,3 @@ servers where isolation and correctness is more important than speed. -.. _`cache-api`: - -config.cache API ------------------- - -The ``config.cache`` object allows other plugins, -including ``conftest.py`` files, -to safely and flexibly store and retrieve values across -test runs because the ``config`` object is available -in many places. - -Under the hood, the cache plugin uses the simple -dumps/loads API of the json stdlib module - -.. currentmodule:: _pytest.cacheprovider - -.. automethod:: Cache.get -.. automethod:: Cache.set -.. automethod:: Cache.makedir diff --git a/doc/en/reference.rst b/doc/en/reference.rst index 20c0549fc..b10b3126c 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -118,7 +118,6 @@ reporting or interaction with exceptions: .. autofunction:: pytest_enter_pdb - Objects ------- @@ -196,3 +195,140 @@ Full reference to objects accessible from :ref:`fixtures ` or hooks .. autoclass:: LineMatcher() :members: +.. autoclass:: _pytest.capture.CaptureFixture() + :members: + + +Fixtures +-------- + +Fixtures are requested by test functions or other fixtures by declaring them as argument names. + + +Example of a test requiring a fixture: + +.. code-block:: python + + def test_output(capsys): + print('hello') + out, err = capsys.readouterr() + assert out == 'hello\n' + + +Example of a fixture requiring another fixture: + +.. code-block:: python + + @pytest.fixture + def db_session(tmpdir): + fn = tmpdir / 'db.file' + return connect(str(fn)) + +For more details, consult the full :ref:`fixtures docs `. + + +fixture decorator signature +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: _pytest.fixtures +.. autofunction:: fixture + :decorator: + + +.. _`cache-api`: + +config.cache +~~~~~~~~~~~~ + +The ``config.cache`` object allows other plugins and fixtures +to store and retrieve values across test runs. To access it from fixtures +request ``pytestconfig`` into your fixture and get it with ``pytestconfig.cache``. + +Under the hood, the cache plugin uses the simple +``dumps``/``loads`` API of the :py:mod:`json` stdlib module. + +.. currentmodule:: _pytest.cacheprovider + +.. automethod:: Cache.get +.. automethod:: Cache.set +.. automethod:: Cache.makedir + + +capsys +~~~~~~ + +.. currentmodule:: _pytest.capture + +.. autofunction:: capsys() + :no-auto-options: + :decorator: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_output(capsys): + print("hello") + captured = capsys.readouterr() + assert captured.out == "hello\n" + + +capsysbinary +~~~~~~~~~~~~ + +.. autofunction:: capsysbinary() + :no-auto-options: + :decorator: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_output(capsysbinary): + print("hello") + captured = capsysbinary.readouterr() + assert captured.out == b"hello\n" + + +capfd +~~~~~~ + +.. autofunction:: capfd() + :no-auto-options: + :decorator: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_system_echo(capfd): + os.system('echo "hello"') + captured = capsys.readouterr() + assert captured.out == "hello\n" + + +capfdbinary +~~~~~~~~~~~~ + +.. autofunction:: capfdbinary() + :no-auto-options: + :decorator: + + Returns an instance of :py:class:`CaptureFixture`. + + Example: + + .. code-block:: python + + def test_system_echo(capfdbinary): + os.system('echo "hello"') + captured = capfdbinary.readouterr() + assert captured.out == b"hello\n" + +