From ca714a7bfcf3eca8ed0102c979e28d9a23891814 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sun, 18 Jan 2026 19:03:22 +0200 Subject: [PATCH 1/3] doc/how-to/fixtures: update `usefixture` on a fixture is now an error --- doc/en/how-to/fixtures.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 5c5a239e8d4..f26723f19e1 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -1746,8 +1746,8 @@ into a configuration file: .. warning:: - Note this mark has no effect in **fixture functions**. For example, - this **will not work as expected**: + ``@pytest.mark.usefixtures`` cannot be used on **fixture functions**. For example, + this is an error: .. code-block:: python @@ -1755,8 +1755,6 @@ into a configuration file: @pytest.fixture def my_fixture_that_sadly_wont_use_my_other_fixture(): ... - This generates a deprecation warning, and will become an error in Pytest 8. - .. _`override fixtures`: Overriding fixtures on various levels From 578fd03598759ce8f0332c7dd2f2002ac09b538d Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sun, 18 Jan 2026 19:04:56 +0200 Subject: [PATCH 2/3] doc/how-to/fixtures: rework confusing usage of backticks Using backticks on the words "override", "global", "root", "locally" makes it look like they are code keywords. I went ahead and also reworded it a bit, as overriding is not only for global fixtures, and not necessarily "locally". --- doc/en/how-to/fixtures.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index f26723f19e1..86adeafe1b9 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -1760,8 +1760,8 @@ into a configuration file: Overriding fixtures on various levels ------------------------------------- -In relatively large test suite, you most likely need to ``override`` a ``global`` or ``root`` fixture with a ``locally`` -defined one, keeping the test code readable and maintainable. +In relatively large test suite, you may want to *override* a fixture, to augment +or change its behavior inside of certain test modules or folders. Override a fixture on a folder (conftest) level ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 5d0c52b6d0a011772fdf388d8f79757ea1821a3e Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sun, 18 Jan 2026 19:20:40 +0200 Subject: [PATCH 3/3] Change uses of "folder" to "directory" It's good to use consistent terminology, especially in the docs. "Directory" is more popular and more ingrained (e.g. in pathlib, `Dir`/`Directory` nodes, etc.). so let's go with that. --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- doc/en/changelog.rst | 2 +- doc/en/explanation/fixtures.rst | 2 +- doc/en/explanation/goodpractices.rst | 2 +- doc/en/explanation/pythonpath.rst | 6 +++--- doc/en/how-to/fixtures.rst | 16 ++++++++-------- doc/en/reference/customize.rst | 2 +- src/_pytest/pathlib.py | 8 ++++---- testing/example_scripts/README.rst | 2 +- testing/plugins_integration/README.rst | 2 +- testing/test_collection.py | 6 +++--- testing/test_pathlib.py | 12 ++++++------ testing/test_tmpdir.py | 8 ++++---- 13 files changed, 35 insertions(+), 35 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5e7282bfd77..6f638ba853b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -13,7 +13,7 @@ If this change fixes an issue, please: Unless your change is trivial or a small documentation fix (e.g., a typo or reword of a small section) please: -- [ ] Create a new changelog file in the `changelog` folder, with a name like `..rst`. See [changelog/README.rst](https://github.com/pytest-dev/pytest/blob/main/changelog/README.rst) for details. +- [ ] Create a new changelog file in the `changelog` directory, with a name like `..rst`. See [changelog/README.rst](https://github.com/pytest-dev/pytest/blob/main/changelog/README.rst) for details. Write sentences in the **past or present tense**, examples: diff --git a/doc/en/changelog.rst b/doc/en/changelog.rst index b4e5cee694e..4695a70e623 100644 --- a/doc/en/changelog.rst +++ b/doc/en/changelog.rst @@ -16,7 +16,7 @@ with advance notice in the **Deprecations** section of releases. fix problems like typo corrections or such. To add a new change log entry, please see https://pip.pypa.io/en/latest/development/contributing/#news-entries - we named the news folder changelog + but note that in pytest the "news/" directory is named "changelog/". .. only:: not is_release diff --git a/doc/en/explanation/fixtures.rst b/doc/en/explanation/fixtures.rst index 53d4796c825..bac3fa02723 100644 --- a/doc/en/explanation/fixtures.rst +++ b/doc/en/explanation/fixtures.rst @@ -152,7 +152,7 @@ If you want to make test data from files available to your tests, a good way to do this is by loading these data in a fixture for use by your tests. This makes use of the automatic caching mechanisms of pytest. -Another good approach is by adding the data files in the ``tests`` folder. +Another good approach is by adding the data files in the ``tests`` directory. There are also community plugins available to help to manage this aspect of testing, e.g. :pypi:`pytest-datadir` and :pypi:`pytest-datafiles`. diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index bbc64ec662d..7c589b57033 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -240,7 +240,7 @@ This results in a drawback compared to the import mode ``importlib``: your test files must have **unique names**. If you need to have test modules with the same name, -as a workaround you might add ``__init__.py`` files to your ``tests`` folder and subfolders, +as a workaround you might add ``__init__.py`` files to your ``tests`` directory and subdirectories, changing them to packages: .. code-block:: text diff --git a/doc/en/explanation/pythonpath.rst b/doc/en/explanation/pythonpath.rst index cb3ae67216a..dd3aec3d235 100644 --- a/doc/en/explanation/pythonpath.rst +++ b/doc/en/explanation/pythonpath.rst @@ -143,8 +143,8 @@ When executing: pytest root/ pytest will find ``foo/bar/tests/test_foo.py`` and realize it is part of a package given that -there's an ``__init__.py`` file in the same folder. It will then search upwards until it can find the -last folder which still contains an ``__init__.py`` file in order to find the package *root* (in +there's an ``__init__.py`` file in the same directory. It will then search upwards until it can find the +last directory which still contains an ``__init__.py`` file in order to find the package *root* (in this case ``foo/``). To load the module, it will insert ``root/`` to the front of :py:data:`sys.path` (if not there already) in order to load ``test_foo.py`` as the *module* ``foo.bar.tests.test_foo``. @@ -175,7 +175,7 @@ When executing: pytest root/ pytest will find ``foo/bar/tests/test_foo.py`` and realize it is NOT part of a package given that -there's no ``__init__.py`` file in the same folder. It will then add ``root/foo/bar/tests`` to +there's no ``__init__.py`` file in the same directory. It will then add ``root/foo/bar/tests`` to :py:data:`sys.path` in order to import ``test_foo.py`` as the *module* ``test_foo``. The same is done with the ``conftest.py`` file by adding ``root/foo`` to :py:data:`sys.path` to import it as ``conftest``. diff --git a/doc/en/how-to/fixtures.rst b/doc/en/how-to/fixtures.rst index 86adeafe1b9..14949994598 100644 --- a/doc/en/how-to/fixtures.rst +++ b/doc/en/how-to/fixtures.rst @@ -1761,10 +1761,10 @@ Overriding fixtures on various levels ------------------------------------- In relatively large test suite, you may want to *override* a fixture, to augment -or change its behavior inside of certain test modules or folders. +or change its behavior inside of certain test modules or directories. -Override a fixture on a folder (conftest) level -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Override a fixture on a directory (conftest) level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Given the tests file structure is: @@ -1784,9 +1784,9 @@ Given the tests file structure is: def test_username(username): assert username == 'username' - subfolder/ + subdir/ conftest.py - # content of tests/subfolder/conftest.py + # content of tests/subdir/conftest.py import pytest @pytest.fixture @@ -1794,11 +1794,11 @@ Given the tests file structure is: return 'overridden-' + username test_something_else.py - # content of tests/subfolder/test_something_else.py + # content of tests/subdir/test_something_else.py def test_username(username): assert username == 'overridden-username' -As you can see, a fixture with the same name can be overridden for certain test folder level. +As you can see, a fixture with the same name can be overridden for certain test directory level. Note that the ``base`` or ``super`` fixture can be accessed from the ``overriding`` fixture easily - used in the example above. @@ -1927,7 +1927,7 @@ Given the tests file structure is: In the example above, a parametrized fixture is overridden with a non-parametrized version, and a non-parametrized fixture is overridden with a parametrized version for certain test module. -The same applies for the test folder level obviously. +The same applies for the test directory level obviously. Using fixtures from other projects diff --git a/doc/en/reference/customize.rst b/doc/en/reference/customize.rst index b2e7d64cc26..9b954bdcab1 100644 --- a/doc/en/reference/customize.rst +++ b/doc/en/reference/customize.rst @@ -272,7 +272,7 @@ check for configuration files as follows: Custom pytest plugin commandline arguments may include a path, as in ``pytest --log-output ../../test.log args``. Then ``args`` is mandatory, - otherwise pytest uses the folder of test.log for rootdir determination + otherwise pytest uses the directory of test.log for rootdir determination (see also :issue:`1435`). A dot ``.`` for referencing to the current working directory is also possible. diff --git a/src/_pytest/pathlib.py b/src/_pytest/pathlib.py index cd15434605d..3619d8cd3fc 100644 --- a/src/_pytest/pathlib.py +++ b/src/_pytest/pathlib.py @@ -225,7 +225,7 @@ def _force_symlink(root: Path, target: str | PurePath, link_to: str | Path) -> N def make_numbered_dir(root: Path, prefix: str, mode: int = 0o700) -> Path: """Create a directory with an increased number as suffix for the given prefix.""" for i in range(10): - # try up to 10 times to create the folder + # try up to 10 times to create the directory max_existing = max(map(parse_num, find_suffixes(root, prefix)), default=-1) new_number = max_existing + 1 new_path = root.joinpath(f"{prefix}{new_number}") @@ -244,7 +244,7 @@ def make_numbered_dir(root: Path, prefix: str, mode: int = 0o700) -> Path: def create_cleanup_lock(p: Path) -> Path: - """Create a lock to prevent premature folder cleanup.""" + """Create a lock to prevent premature directory cleanup.""" lock_path = get_lock_path(p) try: fd = os.open(str(lock_path), os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644) @@ -294,7 +294,7 @@ def maybe_delete_a_numbered_dir(path: Path) -> None: except OSError: # known races: # * other process did a cleanup at the same time - # * deletable folder was found + # * deletable directory was found # * process cwd (Windows) return finally: @@ -336,7 +336,7 @@ def ensure_deletable(path: Path, consider_lock_dead_if_created_before: float) -> def try_cleanup(path: Path, consider_lock_dead_if_created_before: float) -> None: - """Try to cleanup a folder if we can ensure it's deletable.""" + """Try to cleanup a directory if we can ensure it's deletable.""" if ensure_deletable(path, consider_lock_dead_if_created_before): maybe_delete_a_numbered_dir(path) diff --git a/testing/example_scripts/README.rst b/testing/example_scripts/README.rst index 97d0fda5c5d..324673443a3 100644 --- a/testing/example_scripts/README.rst +++ b/testing/example_scripts/README.rst @@ -2,7 +2,7 @@ Example test scripts ===================== -The files in this folder are not direct tests, but rather example test suites that demonstrate certain issues/behaviours. +The files in this directory are not direct tests, but rather example test suites that demonstrate certain issues/behaviours. In the future we will move part of the content of the acceptance tests here in order to have directly testable code instead of writing out things and then running them in nested pytest sessions/subprocesses. diff --git a/testing/plugins_integration/README.rst b/testing/plugins_integration/README.rst index 8f027c3bd35..7d813c5026e 100644 --- a/testing/plugins_integration/README.rst +++ b/testing/plugins_integration/README.rst @@ -1,4 +1,4 @@ -This folder contains tests and support files for smoke testing popular plugins against the current pytest version. +This directory contains tests and support files for smoke testing popular plugins against the current pytest version. The objective is to gauge if any intentional or unintentional changes in pytest break plugins. diff --git a/testing/test_collection.py b/testing/test_collection.py index 39753d80cac..f83bfd9a712 100644 --- a/testing/test_collection.py +++ b/testing/test_collection.py @@ -1659,7 +1659,7 @@ def test_check(): result.stdout.fnmatch_lines(["* 1 passed in *"]) def setup_conftest_and_foo(self, pytester: Pytester) -> None: - """Setup a tests folder to be used to test if modules in that folder can be imported + """Setup a tests directory to be used to test if modules in that directory can be imported due to side-effects of --import-mode or not.""" pytester.makepyfile( **{ @@ -1676,14 +1676,14 @@ def test_check(): ) def test_modules_importable_as_side_effect(self, pytester: Pytester) -> None: - """In import-modes `prepend` and `append`, we are able to import modules from folders + """In import-modes `prepend` and `append`, we are able to import modules from directories containing conftest.py files due to the side effect of changing sys.path.""" self.setup_conftest_and_foo(pytester) result = pytester.runpytest("-v", "--import-mode=prepend") result.stdout.fnmatch_lines(["* 1 passed in *"]) def test_modules_not_importable_as_side_effect(self, pytester: Pytester) -> None: - """In import-mode `importlib`, modules in folders containing conftest.py are not + """In import-mode `importlib`, modules in directories containing conftest.py are not importable, as don't change sys.path or sys.modules as side effect of importing the conftest.py file. """ diff --git a/testing/test_pathlib.py b/testing/test_pathlib.py index 1dec3c6ec78..be20f3fea48 100644 --- a/testing/test_pathlib.py +++ b/testing/test_pathlib.py @@ -1177,24 +1177,24 @@ def test_import_path_imports_correct_file( # Create another x.py module, but in some subdirectories to ensure it is not # accessible from sys.path. - x_in_sub_folder = pytester.path / "a/b/x.py" - x_in_sub_folder.parent.mkdir(parents=True) - x_in_sub_folder.write_text("X = 'a/b/x'", encoding="ascii") + x_in_sub_dir = pytester.path / "a/b/x.py" + x_in_sub_dir.parent.mkdir(parents=True) + x_in_sub_dir.write_text("X = 'a/b/x'", encoding="ascii") # Import our x.py module from the subdirectories. # The 'x.py' module from sys.path was not imported for sure because # otherwise we would get an AssertionError. mod = import_path( - x_in_sub_folder, + x_in_sub_dir, mode=ImportMode.importlib, root=pytester.path, consider_namespace_packages=ns_param, ) - assert mod.__file__ and Path(mod.__file__) == x_in_sub_folder + assert mod.__file__ and Path(mod.__file__) == x_in_sub_dir assert mod.X == "a/b/x" mod2 = import_path( - x_in_sub_folder, + x_in_sub_dir, mode=ImportMode.importlib, root=pytester.path, consider_namespace_packages=ns_param, diff --git a/testing/test_tmpdir.py b/testing/test_tmpdir.py index 363172110d3..12891d81488 100644 --- a/testing/test_tmpdir.py +++ b/testing/test_tmpdir.py @@ -450,10 +450,10 @@ def test_cleanup_ignores_symlink(self, tmp_path): self._do_cleanup(tmp_path) def test_removal_accepts_lock(self, tmp_path): - folder = make_numbered_dir(root=tmp_path, prefix=self.PREFIX) - create_cleanup_lock(folder) - maybe_delete_a_numbered_dir(folder) - assert folder.is_dir() + dir = make_numbered_dir(root=tmp_path, prefix=self.PREFIX) + create_cleanup_lock(dir) + maybe_delete_a_numbered_dir(dir) + assert dir.is_dir() class TestRmRf: