From 1a08209abed384773f6bbf171e3c35c28b3c4d9e Mon Sep 17 00:00:00 2001 From: Tejas Verma Date: Sun, 18 Jan 2026 18:45:16 +0530 Subject: [PATCH 1/4] Docs: clarify conftest usage and fixture import pitfalls --- changelog/13148.doc.rst | 1 + doc/en/how-to/fixtures.rst | 18 +++++++++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) create mode 100644 changelog/13148.doc.rst diff --git a/changelog/13148.doc.rst b/changelog/13148.doc.rst new file mode 100644 index 00000000000..915970ac78e --- /dev/null +++ b/changelog/13148.doc.rst @@ -0,0 +1 @@ +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..589f41073ac 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -391,10 +391,26 @@ 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 +.. note:: + + Fixture *scope* controls lifetime and caching, not visibility. + Visibility is determined by where the fixture is defined (test module, + ``conftest.py``, or plugin). + +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: +.. note:: + + This is the recommended way to share fixtures across multiple test modules. + Avoid importing fixtures from other test files or from ``conftest.py``, + as importing fixtures can cause them to be registered in multiple modules and + lead to confusing behavior (such as fixtures running more than once). + + As a rule of thumb: **never import fixtures from test files or conftest.py, + unless it is only for type annotations**. + .. code-block:: python # content of conftest.py From 687fe933c19864d6ae9dc2376945ef24439aed71 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 18 Jan 2026 13:29:52 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- changelog/13148.doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/changelog/13148.doc.rst b/changelog/13148.doc.rst index 915970ac78e..2c1d1ab5c98 100644 --- a/changelog/13148.doc.rst +++ b/changelog/13148.doc.rst @@ -1 +1 @@ -Clarified fixture visibility, conftest usage, and why importing fixtures is discouraged. +Clarified fixture visibility, conftest usage, and why importing fixtures is discouraged. From 768c74ac6346dde327323597048963f7234dd6ff Mon Sep 17 00:00:00 2001 From: Tejas Verma Date: Sun, 18 Jan 2026 18:45:16 +0530 Subject: [PATCH 3/4] Docs: clarify conftest usage and fixture import pitfalls --- changelog/13148.doc.rst | 3 ++- doc/en/how-to/fixtures.rst | 31 +++++++++++++------------------ 2 files changed, 15 insertions(+), 19 deletions(-) diff --git a/changelog/13148.doc.rst b/changelog/13148.doc.rst index 2c1d1ab5c98..449d8b327ec 100644 --- a/changelog/13148.doc.rst +++ b/changelog/13148.doc.rst @@ -1 +1,2 @@ -Clarified fixture visibility, conftest usage, and why importing fixtures is discouraged. +: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 589f41073ac..a1d8c1cdfd6 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -391,25 +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``. -.. note:: - - Fixture *scope* controls lifetime and caching, not visibility. - Visibility is determined by where the fixture is defined (test module, - ``conftest.py``, or plugin). - 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: - -.. note:: - - This is the recommended way to share fixtures across multiple test modules. - Avoid importing fixtures from other test files or from ``conftest.py``, - as importing fixtures can cause them to be registered in multiple modules and - lead to confusing behavior (such as fixtures running more than once). - - As a rule of thumb: **never import fixtures from test files or conftest.py, - unless it is only for type annotations**. +so that tests from multiple test modules in the directory can access the fixture function. .. code-block:: python @@ -423,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 From 99fcea80209b30a4cf4b024e6527d99634cce6e6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 18 Jan 2026 19:52:00 +0000 Subject: [PATCH 4/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- changelog/13148.doc.rst | 1 - doc/en/how-to/fixtures.rst | 4 ++-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/changelog/13148.doc.rst b/changelog/13148.doc.rst index 449d8b327ec..89a7d8bc6f4 100644 --- a/changelog/13148.doc.rst +++ b/changelog/13148.doc.rst @@ -1,2 +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 a1d8c1cdfd6..f8bf60937a3 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -407,7 +407,7 @@ so that tests from multiple test modules in the directory can access the fixture 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 +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. @@ -416,7 +416,7 @@ fixtures to be registered in more than one place, which can lead to confusing be 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 +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