Add opt-in FunctionDefinition collection tree node (#3926)

Introduce the ``collect_function_definition`` ini option to promote the
internal ``FunctionDefinition`` from a transient parametrization helper to
a real collector node in the collection tree.

The option is tri-state:

- ``hidden`` (default): unchanged flat layout; the definition drives
  parametrization and is kept out of the tree.
- ``pedantic``: insert the definition node between the Module/Class and its
  test functions; function-level markers are scoped to the definition and
  each invocation owns only its callspec markers.
- ``messy``: migration stopgap -- insert the node but transfer the
  function-level markers back onto each invocation to preserve the legacy
  marker layout for code not yet prepared for the new scope; emits a header
  warning.

FunctionDefinition becomes a PyCollector (no longer a Function/Item), so it
is collected rather than run. Invocation node ids stay flat and identical
across all modes, so selection, caching and reporting are unaffected. obj
and instance resolution and getmodpath skip an interposed definition node.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: RonnyPfannschmidt

changelog/14769.bugfix.rst

@@ -0,0 +1,6 @@
+Selecting a parametrized test by its node id (``pytest test_x.py::test_a[1]``)
+now works when the test definition is a node of the collection tree
+(:confval:`collect_function_definition` set to ``pedantic`` or ``messy``). The
+argument matcher compares names level by level, and the definition node carries
+the bare name while the parametrization lives on the items below it; it now
+looks through the definition instead of failing to match.

changelog/3926.improvement.rst

@@ -0,0 +1,15 @@
+Added the :confval:`collect_function_definition` option, which can promote the
+internal ``FunctionDefinition`` to a real node in the collection tree.
+
+When set to ``pedantic``, a ``FunctionDefinition`` collector node is inserted
+between a :class:`~pytest.Module`/:class:`~pytest.Class` and its test functions,
+so that the (possibly parametrized) invocations of each test are collected
+underneath a shared definition node instead of as flat siblings. Function-level
+markers are scoped to the definition node in this mode.
+
+The default ``hidden`` keeps the previous flat layout, and the transitional
+``messy`` value keeps the definition node out of marker resolution for code that
+is not yet prepared for the new scope.
+
+The node ids of the individual test invocations are unchanged in all modes, so
+test selection, caching and reporting behave exactly as before.

doc/en/reference/reference.rst

@@ -937,6 +937,13 @@ Function
     :members:
     :show-inheritance:
 
+ItemDefinition
+~~~~~~~~~~~~~~
+
+.. autoclass:: _pytest.nodes.ItemDefinition()
+    :members:
+    :show-inheritance:
+
 FunctionDefinition
 ~~~~~~~~~~~~~~~~~~
 
@@ -1378,6 +1385,79 @@ passed multiple times. The expected format is ``name=value``. For example::
    variables, that will be expanded. For more information about cache plugin
    please refer to :ref:`cache_provider`.
 
+.. confval:: collect_function_definition
+   :type: ``string``
+   :default: ``hidden``
+
+   .. versionadded:: 9.2
+
+   Controls whether a ``FunctionDefinition`` collector node is inserted into the
+   collection tree between a :class:`~pytest.Module`/:class:`~pytest.Class` and
+   its test functions, grouping the (possibly parametrized) invocations of a test
+   function *underneath* the definition node instead of as flat siblings.
+
+   It accepts three values:
+
+   ``hidden`` (default)
+       Keep the flat layout. The definition node is used only internally to drive
+       parametrization and is kept out of the collection tree.
+
+   ``pedantic``
+       Insert the definition node with correct marker scoping: function-level
+       markers (such as ``@pytest.mark.parametrize`` or custom marks) belong to
+       the definition node, and each invocation only owns its own parameter-set
+       markers. This is the intended target layout.
+
+   ``messy``
+       A stopgap for migration only. It inserts the definition node but transfers
+       the function-level markers back down onto each invocation, reproducing the
+       old (duplicated) marker layout so that code which is not yet prepared for
+       the definition scope keeps working. It emits a warning in the session
+       header and exists purely to buy time; fix the offending code and move to
+       ``pedantic``.
+
+   .. tab:: toml
+
+       .. code-block:: toml
+
+            [pytest]
+            collect_function_definition = "pedantic"
+
+   .. tab:: ini
+
+       .. code-block:: ini
+
+            [pytest]
+            collect_function_definition = pedantic
+
+   For example, given a parametrized test:
+
+   .. code-block:: python
+
+       import pytest
+
+
+       @pytest.mark.parametrize("x", [1, 2])
+       def test_it(x): ...
+
+   the default (``hidden``) layout collects the invocations directly under the
+   module::
+
+       <Module test_it.py>
+         <Function test_it[1]>
+         <Function test_it[2]>
+
+   while ``pedantic`` and ``messy`` group them under a definition node::
+
+       <Module test_it.py>
+         <FunctionDefinition test_it>
+           <Function test_it[1]>
+           <Function test_it[2]>
+
+   This is an opt-in structural change. The node ids of the individual test
+   invocations are unchanged (for example ``test_it.py::test_it[1]``), so test
+   selection, caching and reporting behave exactly as before.
+
 .. confval:: collect_imported_tests
    :type: ``bool``
    :default: ``true``
@@ -3677,6 +3757,14 @@ All the command-line flags can also be obtained by running ``pytest --help``::
       collect_imported_tests (bool):
                             Whether to collect tests in imported modules outside
                             `testpaths`
+      collect_function_definition (string):
+                            How the function-definition collector node
+                            participates in the collection tree. - hidden
+                            (default): keep the flat layout, no node in the tree
+                            - pedantic: insert the node and scope function-level
+                            markers to it - messy: insert the node but transfer
+                            markers down to each invocation to preserve the
+                            legacy marker layout (emits a warning)
       consider_namespace_packages (bool):
                             Consider namespace packages when resolving module
                             names during import

src/_pytest/main.py

@@ -251,6 +251,17 @@ def pytest_addoption(parser: Parser) -> None:
         type="bool",
         default=True,
     )
+    parser.addini(
+        "collect_function_definition",
+        "How the function-definition collector node participates in the "
+        "collection tree.\n"
+        "- hidden (default): keep the flat layout, no node in the tree\n"
+        "- pedantic: insert the node and scope function-level markers to it\n"
+        "- messy: insert the node but transfer markers down to each invocation "
+        "to preserve the legacy marker layout (emits a warning)",
+        type="string",
+        default="hidden",
+    )
     parser.addini(
         "consider_namespace_packages",
         type="bool",
@@ -1007,6 +1018,7 @@ def collect(self) -> Iterator[nodes.Item | nodes.Collector]:
                 # Prune this level.
                 any_matched_in_collector = False
                 for node in reversed(subnodes):
+                    remaining = matchparts[1:]
                     # Path part e.g. `/a/b/` in `/a/b/test_file.py::TestIt::test_it`.
                     if isinstance(matchparts[0], Path):
                         is_match = node.path == matchparts[0]
@@ -1021,7 +1033,13 @@ def collect(self) -> Iterator[nodes.Item | nodes.Collector]:
                     else:
                         if len(matchparts) == 1:
                             # This the last part, one parametrization goes.
-                            if parametrization is not None:
+                            if isinstance(node, nodes.ItemDefinition):
+                                # A definition node carries the bare name, while
+                                # the parametrization is on the items below it.
+                                # Descend and match the same part again there.
+                                is_match = node.name == matchparts[0]
+                                remaining = matchparts
+                            elif parametrization is not None:
                                 # A parametrized arg must match exactly.
                                 is_match = node.name == matchparts[0] + parametrization
                             else:
@@ -1032,7 +1050,7 @@ def collect(self) -> Iterator[nodes.Item | nodes.Collector]:
                         else:
                             is_match = node.name == matchparts[0]
                     if is_match:
-                        work.append((node, matchparts[1:]))
+                        work.append((node, remaining))
                         any_matched_in_collector = True
 
                 if not any_matched_in_collector:

src/_pytest/nodes.py

@@ -644,6 +644,23 @@ class Directory(FSCollector, abc.ABC):
     """
 
 
+class ItemDefinition(Collector, abc.ABC):
+    """Base class for collectors standing for a single test *definition*.
+
+    Its children are the (possibly parametrized) items generated from that one
+    definition. Giving the definition a node of its own makes it addressable:
+    it owns the definition's markers, and node id matching looks through it --
+    the definition carries the bare name, while the ``[...]`` parametrization
+    lives on the items below it.
+
+    :class:`~_pytest.python.FunctionDefinition` is the implementation for
+    Python test functions, inserted into the tree by
+    :confval:`collect_function_definition`.
+
+    .. versionadded:: 9.2
+    """
+
+
 class Item(Node, abc.ABC):
     """Base class of all test invocation items.