Skip to content

Commit d50c3e8

Browse files
Add the "definition" fixture scope (pytest-dev#3926)
Scope.Definition sits between Function and Class, anchored on the definition node, so one fixture instance is shared by all invocations generated from a single definition -- across the parameter sets of one parametrized test, but not between two different tests. The scope needs the definition to actually be in the tree, i.e. collect_function_definition=pedantic. Without it both a definition scoped fixture and parametrize(scope="definition") fail with an explicit ScopeUnavailable message rather than silently degrading to function scope; there is nothing to fall back to that preserves the meaning. --setup-show spells it "D". The scope-to-indentation mapping is now written out explicitly so that adding a scope does not shift the output of the existing ones.
1 parent 382218b commit d50c3e8

8 files changed

Lines changed: 493 additions & 24 deletions

File tree

‎changelog/14857.feature.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
Added the ``"definition"`` fixture scope, which shares one fixture instance
2+
across all invocations generated from a single test definition -- that is,
3+
across the parameter sets of one parametrized test, but not between two
4+
different tests:
5+
6+
.. code-block:: python
7+
8+
@pytest.fixture(scope="definition")
9+
def resource(): ...
10+
11+
12+
@pytest.mark.parametrize("n", [1, 2, 3])
13+
def test_it(resource, n):
14+
# one `resource` for all three parameter sets
15+
...
16+
17+
The scope needs the test definition to be a node of the collection tree, so it
18+
requires :confval:`collect_function_definition` to be set to ``pedantic`` (or
19+
``messy``). Using it without that fails with an explicit error rather than
20+
silently degrading to function scope.
21+
22+
``@pytest.mark.parametrize(..., scope="definition")`` is supported as well and
23+
groups the invocations of one definition by parameter value.

‎doc/en/how-to/fixtures.rst‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -389,7 +389,16 @@ to cause a ``smtp_connection`` fixture function, responsible to create a connect
389389
once per test *module* (the default is to invoke once per test *function*).
390390
Multiple test functions in a test module will thus
391391
each receive the same ``smtp_connection`` fixture instance, thus saving time.
392-
Possible values for ``scope`` are: ``function``, ``class``, ``module``, ``package`` or ``session``.
392+
Possible values for ``scope`` are: ``function``, ``definition``, ``class``,
393+
``module``, ``package`` or ``session``.
394+
395+
.. note::
396+
397+
``definition`` shares one fixture instance across all the invocations
398+
generated from a single test definition -- that is, across the parameter
399+
sets of one parametrized test, but not between two different tests. It
400+
requires the definition to be a node of the collection tree, see
401+
:confval:`collect_function_definition`.
393402

394403
The next example puts the fixture function into a separate ``conftest.py`` file
395404
so that tests from multiple test modules in the directory can

‎src/_pytest/fixtures.py‎

Lines changed: 62 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,23 @@ def get_scope_package(
136136
return node.session
137137

138138

139+
def fail_definition_scope_unavailable(nodeid: str, what: str) -> NoReturn:
140+
"""Fail because the ``"definition"`` scope was used where no
141+
:class:`~_pytest.nodes.ItemDefinition` node exists to anchor it on.
142+
143+
Unlike the other scopes, ``"definition"`` needs the test definition to be a
144+
node of the collection tree; there is nothing to fall back to that would
145+
preserve its meaning of "shared by all invocations of one definition".
146+
"""
147+
fail(
148+
f"ScopeUnavailable: {what} needs the 'definition' scope, but {nodeid} "
149+
f"has no definition node in the collection tree.\n"
150+
f"For Python tests, set the collect_function_definition ini option to "
151+
f"'pedantic' to make function definitions part of the tree.",
152+
pytrace=False,
153+
)
154+
155+
139156
def is_visibility_more_specific(
140157
candidate: FixtureDef[Any], other: FixtureDef[Any]
141158
) -> bool:
@@ -174,6 +191,9 @@ def get_scope_node(node: nodes.Node, scope: Scope) -> nodes.Node | None:
174191
# Type ignored because this is actually safe, see:
175192
# https://github.com/python/mypy/issues/4717
176193
return node.getparent(nodes.Item) # type: ignore[type-abstract]
194+
elif scope is Scope.Definition:
195+
# Type ignored for the same reason as Scope.Function above.
196+
return node.getparent(nodes.ItemDefinition) # type: ignore[type-abstract]
177197
elif scope is Scope.Class:
178198
return node.getparent(_pytest.python.Class)
179199
elif scope is Scope.Module:
@@ -277,6 +297,9 @@ class ParamArgKey:
277297
scoped_item_path: Path | None
278298
#: For Class scope, the class where the item is defined.
279299
item_cls: type | None
300+
#: For Definition scope, the nodeid of the definition the item was
301+
#: generated from.
302+
scoped_definition_id: str | None = None
280303

281304

282305
_V = TypeVar("_V")
@@ -293,6 +316,7 @@ def get_param_argkeys(item: nodes.Item, scope: Scope) -> Iterator[ParamArgKey]:
293316
return
294317

295318
item_cls = None
319+
scoped_definition_id = None
296320
if scope is Scope.Session:
297321
scoped_item_path = None
298322
elif scope is Scope.Package:
@@ -303,14 +327,26 @@ def get_param_argkeys(item: nodes.Item, scope: Scope) -> Iterator[ParamArgKey]:
303327
elif scope is Scope.Class:
304328
scoped_item_path = item.path
305329
item_cls = item.cls # type: ignore[attr-defined]
330+
elif scope is Scope.Definition:
331+
scoped_item_path = item.path
306332
else:
307333
assert_never(scope)
308334

309335
for argname, param in callspec.params.items():
310336
if callspec._arg2scope[argname] != scope:
311337
continue
338+
if scope is Scope.Definition and scoped_definition_id is None:
339+
# Resolved only once a definition-scoped param is actually found:
340+
# items without one need not have a definition node at all. A param
341+
# at this scope can only have been created while the definition was
342+
# a node, so the lookup cannot come up empty here.
343+
definition = get_scope_node(item, Scope.Definition)
344+
assert definition is not None
345+
scoped_definition_id = definition.nodeid
312346
param_key = ParamValueKey(param, callspec.indices[argname])
313-
yield ParamArgKey(argname, param_key, scoped_item_path, item_cls)
347+
yield ParamArgKey(
348+
argname, param_key, scoped_item_path, item_cls, scoped_definition_id
349+
)
314350

315351

316352
def reorder_items(items: Sequence[nodes.Item]) -> list[nodes.Item]:
@@ -546,7 +582,8 @@ def _scope(self) -> Scope:
546582

547583
@property
548584
def scope(self) -> ScopeName:
549-
"""Scope string, one of "function", "class", "module", "package", "session"."""
585+
"""Scope string, one of "function", "definition", "class", "module",
586+
"package", "session"."""
550587
return self._scope.value
551588

552589
@abc.abstractmethod
@@ -908,6 +945,10 @@ def __init__(
908945
if node is None and scope is Scope.Class:
909946
# Fallback to function item itself.
910947
node = self._pyfuncitem
948+
if node is None and scope is Scope.Definition:
949+
fail_definition_scope_unavailable(
950+
self._pyfuncitem.nodeid, f"fixture {fixturedef.argname!r}"
951+
)
911952
assert node, (
912953
f'Could not obtain a node for scope "{scope}" for function {self._pyfuncitem!r}'
913954
)
@@ -1193,7 +1234,8 @@ def __init__(
11931234

11941235
@property
11951236
def scope(self) -> ScopeName:
1196-
"""Scope string, one of "function", "class", "module", "package", "session"."""
1237+
"""Scope string, one of "function", "definition", "class", "module",
1238+
"package", "session"."""
11971239
return self._scope.value
11981240

11991241
@property
@@ -1556,7 +1598,13 @@ def fixture(
15561598
15571599
:param scope:
15581600
The scope for which this fixture is shared; one of ``"function"``
1559-
(default), ``"class"``, ``"module"``, ``"package"`` or ``"session"``.
1601+
(default), ``"definition"``, ``"class"``, ``"module"``, ``"package"``
1602+
or ``"session"``.
1603+
1604+
``"definition"`` shares the fixture across all invocations generated
1605+
from one test definition, i.e. across the parameter sets of a
1606+
parametrized test. It requires the definition to be a node of the
1607+
collection tree, see :confval:`collect_function_definition`.
15601608
15611609
This parameter may also be a callable which receives ``(fixture_name, config)``
15621610
as parameters, and must return a ``str`` with one of the values mentioned above.
@@ -1673,16 +1721,6 @@ def pytest_addoption(parser: Parser) -> None:
16731721
)
16741722

16751723

1676-
def pytest_cmdline_main(config: Config) -> int | ExitCode | None:
1677-
if config.option.showfixtures:
1678-
showfixtures(config)
1679-
return 0
1680-
if config.option.show_fixtures_per_test:
1681-
show_fixtures_per_test(config)
1682-
return 0
1683-
return None
1684-
1685-
16861724
def _resolve_args_directness(
16871725
argnames: Sequence[str],
16881726
indirect: bool | Sequence[str],
@@ -1722,6 +1760,16 @@ def _resolve_args_directness(
17221760
return arg_directness
17231761

17241762

1763+
def pytest_cmdline_main(config: Config) -> int | ExitCode | None:
1764+
if config.option.showfixtures:
1765+
showfixtures(config)
1766+
return 0
1767+
if config.option.show_fixtures_per_test:
1768+
show_fixtures_per_test(config)
1769+
return 0
1770+
return None
1771+
1772+
17251773
def _get_direct_parametrize_args(node: nodes.Node) -> set[str]:
17261774
"""Return all direct parametrization arguments of a node, so we don't
17271775
mistake them for fixtures.

‎src/_pytest/python.py‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1090,12 +1090,25 @@ def parametrize(
10901090
# Add direct parametrizations as fixturedefs to arg2fixturedefs by
10911091
# registering artificial DirectParamFixtureDef's such that later at test
10921092
# setup time we can rely on FixtureDefs to exist for all argnames.
1093-
node = None
1093+
node: nodes.Node | None = None
10941094
# For scopes higher than function, a DirectParamFixtureDef might have
10951095
# already been created for the scope. We thus store and cache the
10961096
# DirectParamFixtureDef on the node related to the scope.
10971097
if scope_ is Scope.Function:
10981098
name2directparamfixturedef = None
1099+
elif scope_ is Scope.Definition:
1100+
if not self.definition.in_collection_tree:
1101+
fixtures.fail_definition_scope_unavailable(
1102+
self.definition.nodeid,
1103+
f"parametrize(scope='definition') in {self.function.__name__}",
1104+
)
1105+
# The definition is the scope node for its own invocations; unlike
1106+
# the other scopes it is not found by looking at ancestors.
1107+
node = self.definition
1108+
default_def: dict[str, DirectParamFixtureDef[object]] = {}
1109+
name2directparamfixturedef = node.stash.setdefault(
1110+
name2directparamfixturedef_key, default_def
1111+
)
10991112
else:
11001113
collector = self.definition.parent
11011114
assert collector is not None
@@ -1512,6 +1525,17 @@ def __init__(
15121525
self.keywords.update((mark.name, mark) for mark in self.own_markers)
15131526
self.keywords.update(self.obj.__dict__)
15141527

1528+
@property
1529+
def in_collection_tree(self) -> bool:
1530+
"""Whether this definition is a node of the collection tree.
1531+
1532+
False in the default ``hidden`` mode of
1533+
:confval:`collect_function_definition`, where the definition only exists
1534+
transiently during collection -- and thus cannot anchor anything at run
1535+
time, such as a ``"definition"`` scoped fixture.
1536+
"""
1537+
return _collect_function_definition_mode(self.config) != "hidden"
1538+
15151539
def collect(self) -> Iterable[nodes.Item | nodes.Collector]:
15161540
children = list(self._generate_functions(self))
15171541
if _collect_function_definition_mode(self.config) == "messy":

‎src/_pytest/scope.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
from typing import Literal
1616

1717

18-
ScopeName = Literal["session", "package", "module", "class", "function"]
18+
ScopeName = Literal["session", "package", "module", "class", "definition", "function"]
1919

2020

2121
@total_ordering
@@ -27,13 +27,19 @@ class Scope(Enum):
2727
2828
->>> higher ->>>
2929
30-
Function < Class < Module < Package < Session
30+
Function < Definition < Class < Module < Package < Session
3131
3232
<<<- lower <<<-
33+
34+
``Definition`` is the scope of a single test *definition*, shared by all
35+
the (possibly parametrized) invocations generated from it. It requires the
36+
definition to be a node in the collection tree -- see
37+
:confval:`collect_function_definition`.
3338
"""
3439

3540
# Scopes need to be listed from lower to higher.
3641
Function = "function"
42+
Definition = "definition"
3743
Class = "class"
3844
Module = "module"
3945
Package = "package"

‎src/_pytest/setuponly.py‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,20 @@ def pytest_fixture_post_finalizer(
6161
del fixturedef.cached_param
6262

6363

64+
# Use smaller indentation the higher the scope. Spelled out rather than derived
65+
# from the Scope order, so that adding a scope does not shift the output of the
66+
# existing ones; Definition shares Function's indentation and is told apart by
67+
# the scope letter.
68+
_SCOPE_INDENTS = {
69+
Scope.Session: 0,
70+
Scope.Package: 1,
71+
Scope.Module: 2,
72+
Scope.Class: 3,
73+
Scope.Definition: 4,
74+
Scope.Function: 4,
75+
}
76+
77+
6478
def _show_fixture_action(
6579
fixturedef: FixtureDef[object], config: Config, msg: str
6680
) -> None:
@@ -70,9 +84,7 @@ def _show_fixture_action(
7084

7185
tw = config.get_terminal_writer()
7286
tw.line()
73-
# Use smaller indentation the higher the scope: Session = 0, Package = 1, etc.
74-
scope_indent = list(reversed(Scope)).index(fixturedef._scope)
75-
tw.write(" " * 2 * scope_indent)
87+
tw.write(" " * 2 * _SCOPE_INDENTS[fixturedef._scope])
7688

7789
scopename = fixturedef.scope[0].upper()
7890
tw.write(f"{msg:<8} {scopename} {fixturedef.argname}")

0 commit comments

Comments
 (0)