diff --git a/changelog/13148.doc.rst b/changelog/13148.doc.rst new file mode 100644 index 00000000000..89a7d8bc6f4 --- /dev/null +++ b/changelog/13148.doc.rst @@ -0,0 +1 @@ +:ref:`Clarified ` fixture visibility, conftest usage, and why importing fixtures is discouraged. diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 5c5a239e8d4..f8bf60937a3 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -391,9 +391,8 @@ Multiple test functions in a test module will thus each receive the same ``smtp_connection`` fixture instance, thus saving time. Possible values for ``scope`` are: ``function``, ``class``, ``module``, ``package`` or ``session``. -The next example puts the fixture function into a separate ``conftest.py`` file -so that tests from multiple test modules in the directory can -access the fixture function: +The next example puts the fixture function into a separate :ref:`conftest.py ` file +so that tests from multiple test modules in the directory can access the fixture function. .. code-block:: python @@ -407,6 +406,18 @@ access the fixture function: def smtp_connection(): return smtplib.SMTP("smtp.gmail.com", 587, timeout=5) +Using ``conftest.py`` is the recommended way to share fixtures across multiple test modules. +The ``scope`` setting controls how long a fixture value is cached +(for example, once per test function or once per module). +The file where the fixture is defined determines which tests are able to use it. + +Avoid importing fixtures from other test files or from ``conftest.py``: importing can cause +fixtures to be registered in more than one place, which can lead to confusing behavior such as +fixtures running more than once. + +As a rule of thumb, don't import fixtures from test files or ``conftest.py`` for runtime use. +If imports are needed only for editor or type checker support, use ``typing.TYPE_CHECKING`` or forward +references so those imports are not executed during test collection. .. code-block:: python