Add TestPath class and test_path fixture

Also change Testdir to be a thin wrapper which only delegates to TestPath. An
alternative would be to subclass and only overwrite the methods that return
Path to convert the return to py.path.local, but this was preferred so we don't
expose Path-returning objects by accident and to expose exactly what we want
in Testdir.

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