add docs and changelog

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