From 581d49635e29c91084227f2263435a15606981b4 Mon Sep 17 00:00:00 2001
From: Ronny Pfannschmidt <ronny.pfannschmidt@redhat.com>
Date: Wed, 27 Jun 2018 06:52:36 +0200
Subject: [PATCH] add docs and changelog

---
 changelog/3623.feature.rst |  1 +
 src/_pytest/experiments.py |  5 +++++
 src/_pytest/pytester.py    | 10 +++++++++-
 tox.ini                    |  2 ++
 4 files changed, 17 insertions(+), 1 deletion(-)
 create mode 100644 changelog/3623.feature.rst
 create mode 100644 src/_pytest/experiments.py

diff --git a/changelog/3623.feature.rst b/changelog/3623.feature.rst
new file mode 100644
index 000000000..2e6f4c428
--- /dev/null
+++ b/changelog/3623.feature.rst
@@ -0,0 +1 @@
+introduce ``pytester.copy_example`` as helper to do acceptance tests against examples from the project
diff --git a/src/_pytest/experiments.py b/src/_pytest/experiments.py
new file mode 100644
index 000000000..da2f19d39
--- /dev/null
+++ b/src/_pytest/experiments.py
@@ -0,0 +1,5 @@
+class PytestExerimentalApiWarning(FutureWarning):
+    "warning category used to denote experiments in pytest"
+
+
+PYTESTER_COPY_EXAMPLE = PytestExerimentalApiWarning()
diff --git a/src/_pytest/pytester.py b/src/_pytest/pytester.py
index 8cbcf6a09..58e4d5d54 100644
--- a/src/_pytest/pytester.py
+++ b/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
 
diff --git a/tox.ini b/tox.ini
index 98abe28f3..2a4f6566b 100644
--- a/tox.ini
+++ b/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