diff --git a/AUTHORS b/AUTHORS index c5cbdb8b6..af0dc62c4 100644 --- a/AUTHORS +++ b/AUTHORS @@ -145,6 +145,7 @@ Joshua Bronson Jurko Gospodnetić Justyna Janczyszyn Kale Kundert +Karl O. Pinc Katarzyna Jachim Katerina Koukiou Kevin Cox diff --git a/changelog/6696.doc.rst b/changelog/6696.doc.rst new file mode 100644 index 000000000..aaa97cc4d --- /dev/null +++ b/changelog/6696.doc.rst @@ -0,0 +1 @@ +Add list of fixtures to start of fixture chapter. diff --git a/doc/en/cache.rst b/doc/en/cache.rst index 6c808fa53..38eab911e 100644 --- a/doc/en/cache.rst +++ b/doc/en/cache.rst @@ -251,7 +251,7 @@ the cache and nothing will be printed: test_caching.py:20: AssertionError 1 failed in 0.12s -See the :ref:`cache-api` for more details. +See the :fixture:`cache-api` for more details. Inspecting Cache content diff --git a/doc/en/changelog.rst b/doc/en/changelog.rst index f0ad2b8ec..09c7e82b0 100644 --- a/doc/en/changelog.rst +++ b/doc/en/changelog.rst @@ -180,7 +180,7 @@ Features rather than implicitly. -- `#5914 `_: :ref:`testdir` learned two new functions, :py:func:`~_pytest.pytester.LineMatcher.no_fnmatch_line` and +- `#5914 `_: :fixture:`testdir` learned two new functions, :py:func:`~_pytest.pytester.LineMatcher.no_fnmatch_line` and :py:func:`~_pytest.pytester.LineMatcher.no_re_match_line`. The functions are used to ensure the captured text *does not* match the given diff --git a/doc/en/conf.py b/doc/en/conf.py index 85521309f..1aa1f6b0a 100644 --- a/doc/en/conf.py +++ b/doc/en/conf.py @@ -373,10 +373,18 @@ def configure_logging(app: "sphinx.application.Sphinx") -> None: def setup(app: "sphinx.application.Sphinx") -> None: # from sphinx.ext.autodoc import cut_lines # app.connect('autodoc-process-docstring', cut_lines(4, what=['module'])) + app.add_crossref_type( + "fixture", + "fixture", + objname="built-in fixture", + indextemplate="pair: %s; fixture", + ) + app.add_object_type( "confval", "confval", objname="configuration value", indextemplate="pair: %s; configuration value", ) + configure_logging(app) diff --git a/doc/en/fixture.rst b/doc/en/fixture.rst index a9352a19f..24d911d33 100644 --- a/doc/en/fixture.rst +++ b/doc/en/fixture.rst @@ -40,6 +40,74 @@ both styles, moving incrementally from classic to new style, as you prefer. You can also start out from existing :ref:`unittest.TestCase style ` or :ref:`nose based ` projects. +:ref:`Fixtures ` are defined using the +:ref:`@pytest.fixture ` decorator, :ref:`described +below `. Pytest has useful built-in fixtures, listed here +for reference: + + :fixture:`capfd` + Capture, as text, output to file descriptors ``1`` and ``2``. + + :fixture:`capfdbinary` + Capture, as bytes, output to file descriptors ``1`` and ``2``. + + :fixture:`caplog` + Control logging and access log entries. + + :fixture:`capsys` + Capture, as text, output to ``sys.stdout`` and ``sys.stderr``. + + :fixture:`capsysbinary` + Capture, as bytes, output to ``sys.stdout`` and ``sys.stderr``. + + :fixture:`cache` + Store and retrieve values across pytest runs. + + :fixture:`doctest_namespace` + Provide a dict injected into the docstests namespace. + + :fixture:`monkeypatch` + Temporarily modify classes, functions, dictionaries, + ``os.environ``, and other objects. + + :fixture:`pytestconfig` + Access to configuration values, pluginmanager and plugin hooks. + + :fixture:`record_property` + Add extra properties to the test. + + :fixture:`record_testsuite_property` + Add extra properties to the test suite. + + :fixture:`recwarn` + Record warnings emitted by test functions. + + :fixture:`request` + Provide information on the executing test function. + + :fixture:`testdir` + Provide a temporary test directory to aid in running, and + testing, pytest plugins. + + :fixture:`tmp_path` + Provide a :class:`pathlib.Path` object to a temporary directory + which is unique to each test function. + + :fixture:`tmp_path_factory` + Make session-scoped temporary directories and return + :class:`pathlib.Path` objects. + + :fixture:`tmpdir` + Provide a :class:`py.path.local` object to a temporary + directory which is unique to each test function; + replaced by :fixture:`tmp_path`. + + .. _`py.path.local`: https://py.readthedocs.io/en/latest/path.html + + :fixture:`tmpdir_factory` + Make session-scoped temporary directories and return + :class:`py.path.local` objects; + replaced by :fixture:`tmp_path_factory`. .. _`funcargs`: .. _`funcarg mechanism`: diff --git a/doc/en/reference.rst b/doc/en/reference.rst index fe0e331b6..64e5881fa 100644 --- a/doc/en/reference.rst +++ b/doc/en/reference.rst @@ -243,6 +243,8 @@ Will create and attach a :class:`Mark <_pytest.mark.structures.Mark>` object to mark.kwargs == {"method": "thread"} +.. _`fixtures-api`: + Fixtures -------- @@ -273,6 +275,8 @@ Example of a fixture requiring another fixture: For more details, consult the full :ref:`fixtures docs `. +.. _`pytest.fixture-api`: + @pytest.fixture ~~~~~~~~~~~~~~~ @@ -280,7 +284,7 @@ For more details, consult the full :ref:`fixtures docs `. :decorator: -.. _`cache-api`: +.. fixture:: cache config.cache ~~~~~~~~~~~~ @@ -301,6 +305,8 @@ Under the hood, the cache plugin uses the simple .. automethod:: Cache.makedir +.. fixture:: capsys + capsys ~~~~~~ @@ -326,6 +332,8 @@ capsys :members: +.. fixture:: capsysbinary + capsysbinary ~~~~~~~~~~~~ @@ -346,6 +354,8 @@ capsysbinary assert captured.out == b"hello\n" +.. fixture:: capfd + capfd ~~~~~~ @@ -366,6 +376,8 @@ capfd assert captured.out == "hello\n" +.. fixture:: capfdbinary + capfdbinary ~~~~~~~~~~~~ @@ -386,6 +398,8 @@ capfdbinary assert captured.out == b"hello\n" +.. fixture:: doctest_namespace + doctest_namespace ~~~~~~~~~~~~~~~~~ @@ -404,6 +418,8 @@ doctest_namespace For more details: :ref:`doctest_namespace`. +.. fixture:: request + request ~~~~~~~ @@ -415,12 +431,16 @@ The ``request`` fixture is a special fixture providing information of the reques :members: +.. fixture:: pytestconfig + pytestconfig ~~~~~~~~~~~~ .. autofunction:: _pytest.fixtures.pytestconfig() +.. fixture:: record_property + record_property ~~~~~~~~~~~~~~~~~~~ @@ -429,6 +449,8 @@ record_property .. autofunction:: _pytest.junitxml.record_property() +.. fixture:: record_testsuite_property + record_testsuite_property ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -436,6 +458,9 @@ record_testsuite_property .. autofunction:: _pytest.junitxml.record_testsuite_property() + +.. fixture:: caplog + caplog ~~~~~~ @@ -450,6 +475,8 @@ caplog :members: +.. fixture:: monkeypatch + monkeypatch ~~~~~~~~~~~ @@ -465,7 +492,8 @@ monkeypatch .. autoclass:: _pytest.monkeypatch.MonkeyPatch :members: -.. _testdir: + +.. fixture:: testdir testdir ~~~~~~~ @@ -493,6 +521,8 @@ To use it, include in your top-most ``conftest.py`` file: :members: +.. fixture:: recwarn + recwarn ~~~~~~~ @@ -516,6 +546,8 @@ Each recorded warning is an instance of :class:`warnings.WarningMessage`. differently; see :ref:`ensuring_function_triggers`. +.. fixture:: tmp_path + tmp_path ~~~~~~~~ @@ -527,6 +559,8 @@ tmp_path :no-auto-options: +.. fixture:: tmp_path_factory + tmp_path_factory ~~~~~~~~~~~~~~~~ @@ -542,6 +576,8 @@ tmp_path_factory .. automethod:: TempPathFactory.getbasetemp +.. fixture:: tmpdir + tmpdir ~~~~~~ @@ -553,6 +589,8 @@ tmpdir :no-auto-options: +.. fixture:: tmpdir_factory + tmpdir_factory ~~~~~~~~~~~~~~