From 9cb72dbc4301a92a28f456bfc17468cd8271861a Mon Sep 17 00:00:00 2001
From: Chris Dent <chris.dent@gmail.com>
Date: Tue, 20 Sep 2016 19:28:19 +0100
Subject: [PATCH] Add some doc and FAQ about quieting pytest warnings (#172)

As it will take some time and effort to replace the existing yield
tests, add some hopefully helpful information on how to deal with
the warnings.
---
 docs/source/faq.rst    | 10 ++++++++++
 docs/source/loader.rst | 11 +++++++++++
 2 files changed, 21 insertions(+)

diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index c0446df..34b263b 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -21,6 +21,16 @@ Is gabbi only for testing Python-based APIs?
 No, you can use :doc:`gabbi-run <runner>` to test an HTTP service
 built in any programming language.
 
+Workarounds
+~~~~~~~~~~~
+
+pytest produces warnings about yield tests. Can I make them stop?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, run as ``py.test --disable-pytest-warnings`` to quiet the
+warnings. Or use a version of pytest less than ``3.0``. For more details
+see :ref:`pytest <pytest_loader>`.
+
 Testing Style
 ~~~~~~~~~~~~~
 
diff --git a/docs/source/loader.rst b/docs/source/loader.rst
index 453d925..aca6842 100644
--- a/docs/source/loader.rst
+++ b/docs/source/loader.rst
@@ -64,6 +64,8 @@ advanced options, including using ``testrepository`` and
 pytest
 ~~~~~~
 
+.. _pytest_loader:
+
 Since pytest does not support the ``load_tests`` system, a different
 way of generating tests is required. A test file must be created
 that calls :meth:`~gabbi.driver.py_test_generator` and yields the
@@ -76,6 +78,15 @@ This can then be run with the usual pytest commands. For example::
 
    py.test -svx pytest-example.py
 
+.. warning:: In ``pytest>=3.0`` yield tests are deprecated and using
+             them will cause pytest to produce a warning. If you
+             wish to ignore and hide these warnings add the
+             ``--disable-pytest-warnings`` parameter to the
+             invocation of ``py.test`` or use a version of pytest
+             earlier than version ``3.0``. A new way of creating gabbi
+             tests that works more effectively with modern pytest is
+             being developed.
+
 .. _source distribution: https://github.com/cdent/gabbi
 .. _the tutorial repo: https://github.com/cdent/gabbi-demo
 .. _pytest: http://pytest.org/