Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog/13148.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
:ref:`Clarified <smtpshared>` fixture visibility, conftest usage, and why importing fixtures is discouraged.
17 changes: 14 additions & 3 deletions doc/en/how-to/fixtures.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <conftest>` file
so that tests from multiple test modules in the directory can access the fixture function.

.. code-block:: python
Expand All @@ -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
Expand Down