From 80d165475b4c1ef1f70ed01db3b7b08b627cb91b Mon Sep 17 00:00:00 2001
From: Joan Massich <sik@visor.udg.edu>
Date: Thu, 7 Sep 2017 10:28:52 +0200
Subject: [PATCH] Add documentation

---
 _pytest/recwarn.py  | 16 ++++++++++++++++
 doc/en/warnings.rst | 15 ++++++++++++++-
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/_pytest/recwarn.py b/_pytest/recwarn.py
index 4f7efba99..c9f86a483 100644
--- a/_pytest/recwarn.py
+++ b/_pytest/recwarn.py
@@ -100,6 +100,22 @@ def warns(expected_warning, *args, **kwargs):
 
         >>> with warns(RuntimeWarning):
         ...    warnings.warn("my warning", RuntimeWarning)
+
+    In the context manager form you may use the keyword argument ``match`` to assert
+    that the exception matches a text or regex::
+
+        >>> with warns(UserWarning, match='must be 0 or None'):
+        ...     warnings.warn("value must be 0 or None", UserWarning)
+
+        >>> with warns(UserWarning, match=r'must be \d+$'):
+        ...     warnings.warn("value must be 42", UserWarning)
+
+        >>> with warns(UserWarning, match=r'must be \d+$'):
+        ...     warnings.warn("this is not here", UserWarning)
+        Traceback (most recent call last):
+          ...
+        Failed: DID NOT WARN. No warnings of type ...UserWarning... was emitted...
+
     """
     match_expr = None
     if not args:
diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index c84277173..ac26068c4 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -168,7 +168,20 @@ which works in a similar manner to :ref:`raises <assertraises>`::
         with pytest.warns(UserWarning):
             warnings.warn("my warning", UserWarning)
 
-The test will fail if the warning in question is not raised.
+The test will fail if the warning in question is not raised. The keyword
+argument ``match`` to assert that the exception matches a text or regex::
+
+    >>> with warns(UserWarning, match='must be 0 or None'):
+    ...     warnings.warn("value must be 0 or None", UserWarning)
+
+    >>> with warns(UserWarning, match=r'must be \d+$'):
+    ...     warnings.warn("value must be 42", UserWarning)
+
+    >>> with warns(UserWarning, match=r'must be \d+$'):
+    ...     warnings.warn("this is not here", UserWarning)
+    Traceback (most recent call last):
+      ...
+    Failed: DID NOT WARN. No warnings of type ...UserWarning... was emitted...
 
 You can also call ``pytest.warns`` on a function or code string::