Updated documentation from txt to rst

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

1 files changed, 46 insertions, 0 deletions

diff --git a/doc/en/recwarn.rst b/doc/en/recwarn.rst
new file mode 100644
index 000000000..c07a2cbe7
--- /dev/null
+++ b/doc/en/recwarn.rst
@@ -0,0 +1,46 @@
+
+Asserting deprecation and other warnings
+=====================================================
+
+.. _function_argument:
+
+The recwarn function argument
+------------------------------------
+
+You can use the ``recwarn`` funcarg to assert that code triggers
+warnings through the Python warnings system. Here is a simple
+self-contained test::
+
+    # content of test_recwarn.py
+    def test_hello(recwarn):
+        from warnings import warn
+        warn("hello", DeprecationWarning)
+        w = recwarn.pop(DeprecationWarning)
+        assert issubclass(w.category, DeprecationWarning)
+        assert 'hello' in str(w.message)
+        assert w.filename
+        assert w.lineno
+
+The ``recwarn`` function argument provides these methods:
+
+.. method:: pop(category=None)
+
+    Return last warning matching the category.
+
+.. method:: clear()
+
+    Clear list of warnings
+
+
+.. _ensuring_function_triggers:
+
+Ensuring a function triggers a deprecation warning
+-------------------------------------------------------
+
+You can also call a global helper for checking
+that a certain function call triggers a ``DeprecationWarning``::
+
+    import pytest
+
+    def test_global():
+        pytest.deprecated_call(myfunction, 17)