add docs and changelog

changelog/3623.feature.rst

@@ -0,0 +1 @@
+introduce ``pytester.copy_example`` as helper to do acceptance tests against examples from the project

src/_pytest/experiments.py

@@ -0,0 +1,5 @@
+class PytestExerimentalApiWarning(FutureWarning):
+    "warning category used to denote experiments in pytest"
+
+
+PYTESTER_COPY_EXAMPLE = PytestExerimentalApiWarning()

src/_pytest/pytester.py

@@ -633,12 +633,20 @@ class Testdir(object):
         return p
 
     def copy_example(self, name):
+        from . import experiments
+        import warnings
+
+        warnings.warn(experiments.PYTESTER_COPY_EXAMPLE, stacklevel=2)
         example_dir = self.request.config.getini("pytester_example_dir")
+        if example_dir is None:
+            raise ValueError("pytester_example_dir is unset, can't copy examples")
         example_path = self.request.config.rootdir.join(example_dir, name)
         if example_path.isdir() and not example_path.join("__init__.py").isfile():
             example_path.copy(self.tmpdir)
-        else:
+        elif example_path.isfile():
             example_path.copy(self.tmpdir.join(example_path.basename))
+        else:
+            raise LookupError("example is not found as a file or directory")
 
     Session = Session
 

tox.ini

@@ -204,6 +204,8 @@ filterwarnings =
     ignore:.*type argument to addoption.*:DeprecationWarning
     # produced by python >=3.5 on execnet (pytest-xdist)
     ignore:.*inspect.getargspec.*deprecated, use inspect.signature.*:DeprecationWarning
+    #pytests own futurewarnings
+    ignore::_pytest.experiments.PytestExerimentalApiWarning
 pytester_example_dir = testing/example_scripts
 [flake8]
 max-line-length = 120