From f0ecb25acd2faefa31c460c43b580b071393bdf9 Mon Sep 17 00:00:00 2001
From: Nick Murphy <namurphy@cfa.harvard.edu>
Date: Fri, 1 Feb 2019 21:48:29 -0500
Subject: [PATCH 1/4] Document custom failure messages for missing warnings

---
 doc/en/warnings.rst | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index 8f0244aea..cfa966488 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -233,7 +233,7 @@ You can also use it as a contextmanager::
 .. _warns:
 
 Asserting warnings with the warns function
------------------------------------------------
+------------------------------------------
 
 .. versionadded:: 2.8
 
@@ -291,7 +291,7 @@ Alternatively, you can examine raised warnings in detail using the
 .. _recwarn:
 
 Recording warnings
-------------------------
+------------------
 
 You can record raised warnings either using ``pytest.warns`` or with
 the ``recwarn`` fixture.
@@ -329,6 +329,26 @@ warnings, or index into it to get a particular recorded warning.
 
 Full API: :class:`WarningsRecorder`.
 
+.. _custom_failure_messages:
+
+Custom failure messages
+-----------------------
+
+Recording warnings provides an opportunity to produce custom test
+failure messages for when no warnings are issued or other conditions
+are met.
+
+.. code-block:: python
+
+    def test():
+        with pytest.warns(Warning) as record:
+            f()
+            if not record:
+                pytest.fail('Expected a warning!')
+
+If no warnings are issued when calling ``f``, then ``not record`` will
+evaluate to ``False``.  You can then call ``pytest.fail`` with a
+custom error message.
 
 .. _internal-warnings:
 

From 8003d8d2798cd23cf7b295f5ec7b5a8689893783 Mon Sep 17 00:00:00 2001
From: Nick Murphy <namurphy@cfa.harvard.edu>
Date: Fri, 1 Feb 2019 21:55:01 -0500
Subject: [PATCH 2/4] Update AUTHORS

---
 AUTHORS | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AUTHORS b/AUTHORS
index 35e07dcb4..e8b0166ff 100644
--- a/AUTHORS
+++ b/AUTHORS
@@ -173,6 +173,7 @@ Nathaniel Waisbrot
 Ned Batchelder
 Neven Mundar
 Nicholas Devenish
+Nicholas Murphy
 Niclas Olofsson
 Nicolas Delaby
 Oleg Pidsadnyi

From 4e93dc2c97382bf897df3e2d5e8e002cc48a15b3 Mon Sep 17 00:00:00 2001
From: Nick Murphy <namurphy@cfa.harvard.edu>
Date: Fri, 1 Feb 2019 22:11:41 -0500
Subject: [PATCH 3/4] Update changelog for pytest.warns doc update

---
 changelog/4709.doc.rst | 2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 changelog/4709.doc.rst

diff --git a/changelog/4709.doc.rst b/changelog/4709.doc.rst
new file mode 100644
index 000000000..5f21728f6
--- /dev/null
+++ b/changelog/4709.doc.rst
@@ -0,0 +1,2 @@
+Document how to customize test failure messages when using
+``pytest.warns``.

From 584c052da41c83692f437b75ae3eacb8faba8b05 Mon Sep 17 00:00:00 2001
From: Bruno Oliveira <nicoddemus@gmail.com>
Date: Tue, 5 Feb 2019 19:04:26 -0200
Subject: [PATCH 4/4] Fix linting and change False to True as requested in
 review

---
 doc/en/warnings.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/en/warnings.rst b/doc/en/warnings.rst
index cfa966488..11f73f43e 100644
--- a/doc/en/warnings.rst
+++ b/doc/en/warnings.rst
@@ -344,10 +344,10 @@ are met.
         with pytest.warns(Warning) as record:
             f()
             if not record:
-                pytest.fail('Expected a warning!')
+                pytest.fail("Expected a warning!")
 
 If no warnings are issued when calling ``f``, then ``not record`` will
-evaluate to ``False``.  You can then call ``pytest.fail`` with a
+evaluate to ``True``.  You can then call ``pytest.fail`` with a
 custom error message.
 
 .. _internal-warnings: