Merge pull request #7345 from The-Compiler/fixture-docs

doc: Explain indirect parametrization and markers for fixtures

changelog/7345.doc.rst

@@ -0,0 +1 @@
+Explain indirect parametrization and markers for fixtures

doc/en/example/parametrize.rst

@@ -351,6 +351,30 @@ And then when we run the test:
 
 The first invocation with ``db == "DB1"`` passed while the second with ``db == "DB2"`` failed.  Our ``db`` fixture function has instantiated each of the DB values during the setup phase while the ``pytest_generate_tests`` generated two according calls to the ``test_db_initialized`` during the collection phase.
 
+Indirect parametrization
+---------------------------------------------------
+
+Using the ``indirect=True`` parameter when parametrizing a test allows to
+parametrize a test with a fixture receiving the values before passing them to a
+test:
+
+.. code-block:: python
+
+    import pytest
+
+
+    @pytest.fixture
+    def fixt(request):
+        return request.param * 3
+
+
+    @pytest.mark.parametrize("fixt", ["a", "b"], indirect=True)
+    def test_indirect(fixt):
+        assert len(fixt) == 3
+
+This can be used, for example, to do more expensive setup at test run time in
+the fixture, rather than having to run those setup steps at collection time.
+
 .. regendoc:wipe
 
 Apply indirect on particular arguments

doc/en/fixture.rst

@@ -665,6 +665,37 @@ Running it:
 voila! The ``smtp_connection`` fixture function picked up our mail server name
 from the module namespace.
 
+.. _`using-markers`:
+
+Using markers to pass data to fixtures
+-------------------------------------------------------------
+
+Using the :py:class:`request <FixtureRequest>` object, a fixture can also access
+markers which are applied to a test function. This can be useful to pass data
+into a fixture from a test:
+
+.. code-block:: python
+
+    import pytest
+
+
+    @pytest.fixture
+    def fixt(request):
+        marker = request.node.get_closest_marker("fixt_data")
+        if marker is None:
+            # Handle missing marker in some way...
+            data = None
+        else:
+            data = marker.args[0]
+
+        # Do something with the data
+        return data
+
+
+    @pytest.mark.fixt_data(42)
+    def test_fixt(fixt):
+        assert fixt == 42
+
 .. _`fixture-factory`:
 
 Factories as fixtures