New pytester fixture (#7854)

changelog/7425.feature.rst

@@ -0,0 +1,5 @@
+New :fixture:`pytester` 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.
+
+Internally, the old :class:`Testdir` is now a thin wrapper around :class:`Pytester`, preserving the old interface.

doc/en/reference.rst

@@ -499,25 +499,29 @@ monkeypatch
     :members:
 
 
-.. fixture:: testdir
+.. fixture:: pytester
 
-testdir
-~~~~~~~
+pytester
+~~~~~~~~
+
+.. versionadded:: 6.2
 
 .. 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:`Pytester` instance that can be used to run and test pytest itself.
+
+It provides an empty directory where pytest can be executed in isolation, and contains facilities
+to write tests, 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:: Pytester()
     :members:
 
 .. autoclass:: RunResult()
@@ -526,6 +530,15 @@ To use it, include in your top-most ``conftest.py`` file:
 .. autoclass:: LineMatcher()
     :members:
 
+.. fixture:: testdir
+
+testdir
+~~~~~~~
+
+Identical to :fixture:`pytester`, 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:`pytester`.
 
 .. fixture:: recwarn