Issues a warning when a function is not collected as a test case just because it uses @pytest.fixture (#12989)

changelog/12989.improvement.rst

@@ -0,0 +1,8 @@
+Issues a warning when a function is not collected as a test case just because it uses :py:func:`pytest.fixture`.
+This helps beginners distinguish fixtures from tests; experienced users can ignore the warning via config.
+
+.. code-block:: ini
+
+    [pytest]
+    filterwarnings =
+        ignore:.*becomes a fixture.*:pytest.PytestCollectionWarning

doc/en/explanation/fixtures.rst

@@ -88,6 +88,65 @@ prefer.  You can also start out from existing :ref:`unittest.TestCase
 style <unittest.TestCase>`.
 
 
+Distinguishing fixtures and tests
+------------------------------------
+
+Fixtures and tests may seem similar: both are functions (or methods) and both can utilize fixtures.
+However, there is a fundamental difference:
+
+- **Tests** are the leading role.
+  They can actively use :ref:`mark <mark>` and fixtures.
+
+- **Fixtures** are supporting role.
+  They cannot use mark or tests and only be used directly or indirectly by test cases.
+
+
+Two classic traps:
+
+
+- Will not fail, because adding any tags to the fixture is invalid
+
+.. code-block:: python
+
+    import warnings
+
+
+    @pytest.fixture
+    @pytest.mark.filterwarnings("error")  # fixture cannot use mark
+    def server():
+        print("fixture is running!")
+
+
+    def test_foo(server):
+        warnings.warn(UserWarning("api v1, should use functions from v2"))
+
+
+
+- No code will execute, because the ``test_foo`` becomes a fixture after using ``@pytest.fixture``
+
+
+.. code-block:: python
+
+    @pytest.fixture
+    def server():
+        print("fixture is running!")
+
+
+    @pytest.fixture  # turn test case into fixtures
+    def test_foo(server):
+        warnings.warn(UserWarning("api v1, should use functions from v2"))
+
+
+
+.. versionadded:: 8.0
+
+Applying a mark to a fixture function now issues a warning and will become an error in pytest 9.0.
+
+
+.. versionadded:: 8.4
+
+Issues a warning when a function is not collected as a test case just because it uses ``@pytest.fixture``
+
 
 Fixture errors
 --------------

pyproject.toml

@@ -403,6 +403,7 @@ filterwarnings = [
     "ignore:VendorImporter\\.find_spec\\(\\) not found; falling back to find_module\\(\\):ImportWarning",
     # https://github.com/pytest-dev/execnet/pull/127
     "ignore:isSet\\(\\) is deprecated, use is_set\\(\\) instead:DeprecationWarning",
+    "ignore:.*becomes a fixture.*:pytest.PytestCollectionWarning",
 ]
 pytester_example_dir = "testing/example_scripts"
 markers = [

src/_pytest/python.py

@@ -354,6 +354,16 @@
 
     def istestfunction(self, obj: object, name: str) -> bool:
         if self.funcnamefilter(name) or self.isnosetest(obj):
+            if isinstance(obj, fixtures.FixtureFunctionDefinition):
+                self.warn(
+                    PytestCollectionWarning(
+                        f"cannot collect test function {name!r},"
+                        f"because it used the '@pytest.fixture' than becomes a fixture "
+                        f"(from: {self.nodeid})"
+                    )
+                )
+                return False
+
             if isinstance(obj, (staticmethod, classmethod)):
                 # staticmethods and classmethods need to be unwrapped.
                 obj = safe_getattr(obj, "__func__", False)

testing/python/collect.py

@@ -783,6 +783,26 @@ def test_function_with_square_brackets(self, pytester: Pytester) -> None:
             ]
         )
 
+    @pytest.mark.filterwarnings("default::UserWarning")
+    def test_function_used_fixture(self, pytester: Pytester):
+        pytester.makeini("[pytest]")
+        pytester.makepyfile(
+            """
+            import pytest
+            @pytest.fixture
+            def test_function():
+                pass
+        """
+        )
+        result = pytester.runpytest()
+        result.stdout.fnmatch_lines(
+            [
+                "collected 0 items",
+                "*== warnings summary ==*",
+                "*because it used the '@pytest.fixture' than becomes a fixture*",
+            ]
+        )
+
 
 class TestSorting:
     def test_check_equality(self, pytester: Pytester) -> None: