New testdir-like fixture using pathlib

changelog/7425.feature.rst

@@ -0,0 +1,3 @@
+New :fixture:`test_path` fixture, which is identical to :fixture:`testdir` but its methods return :class:`pathlib.Path` when appropriate instead of ``py.path.local``.
+
+This is part of the movement to use :class:`pathlib.Path` objects internally, in order to remove the dependency to ``py`` in the future.

doc/en/reference.rst

@@ -494,25 +494,27 @@ monkeypatch
     :members:
 
 
-.. fixture:: testdir
+.. fixture:: test_path
 
-testdir
-~~~~~~~
+test_path
+~~~~~~~~~
 
 .. currentmodule:: _pytest.pytester
 
-This fixture provides a :class:`Testdir` instance useful for black-box testing of test files, making it ideal to
-test plugins.
+Provides a :class:`TestPath` instance that can be used to run and test pytest itself.
+
+It provides an empty folder where pytest can be executed in isolation, and contains facilities
+to write test, configuration files, and match against expected output.
 
-To use it, include in your top-most ``conftest.py`` file:
+To use it, include in your topmost ``conftest.py`` file:
 
 .. code-block:: python
 
     pytest_plugins = "pytester"
 
 
 
-.. autoclass:: Testdir()
+.. autoclass:: TestPath()
     :members:
 
 .. autoclass:: RunResult()
@@ -521,6 +523,15 @@ To use it, include in your top-most ``conftest.py`` file:
 .. autoclass:: LineMatcher()
     :members:
 
+.. fixture:: testdir
+
+testdir
+~~~~~~~
+
+Identical to :fixture:`test_path`, but provides an instance whose methods return
+legacy ``py.path.local`` objects instead when applicable.
+
+New code should avoid using :fixture:`testdir` in favor of :fixture:`test_path`.
 
 .. fixture:: recwarn