From aeae183c757a72b97a1231f6ce389fd082b9e998 Mon Sep 17 00:00:00 2001
From: Olga Matoula <olgamatoula@gmail.com>
Date: Sun, 9 Jan 2022 22:09:30 +0000
Subject: [PATCH] Add docs on pytest.warns(None) deprecation

---
 changelog/9404.doc.rst     |  1 +
 doc/en/deprecations.rst    | 27 ++++++++++++++++++++++++---
 src/_pytest/deprecated.py  |  5 ++++-
 testing/deprecated_test.py |  7 +++++--
 4 files changed, 34 insertions(+), 6 deletions(-)
 create mode 100644 changelog/9404.doc.rst

diff --git a/changelog/9404.doc.rst b/changelog/9404.doc.rst
new file mode 100644
index 000000000..70e4c6d58
--- /dev/null
+++ b/changelog/9404.doc.rst
@@ -0,0 +1 @@
+Added extra documentation on alternatives to common misuses of `pytest.warns(None)` ahead of its deprecation.
diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst
index 6351d1f6e..455a252c7 100644
--- a/doc/en/deprecations.rst
+++ b/doc/en/deprecations.rst
@@ -221,11 +221,32 @@ Using ``pytest.warns(None)``
 
 .. deprecated:: 7.0
 
-:func:`pytest.warns(None) <pytest.warns>` is now deprecated because many people used
-it to mean "this code does not emit warnings", but it actually had the effect of
-checking that the code emits at least one warning of any type - like ``pytest.warns()``
+:func:`pytest.warns(None) <pytest.warns>` is now deprecated because it was frequently misused.
+Its correct usage was checking that the code emits at least one warning of any type - like ``pytest.warns()``
 or ``pytest.warns(Warning)``.
 
+If you are looking to:
+
+-  ensure that **no** warnings are emitted, consider using
+
+.. code-block:: python
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+
+- suppress warnings, you could use
+
+.. code-block:: python
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+
+- ensure that **any** warning is emitted, please use
+
+.. code-block:: python
+
+    with pytest.warns():
+        pass
 
 The ``--strict`` command-line option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py
index f68aea37e..2f7ab5bde 100644
--- a/src/_pytest/deprecated.py
+++ b/src/_pytest/deprecated.py
@@ -89,7 +89,10 @@ NODE_CTOR_FSPATH_ARG = UnformattedWarning(
 
 WARNS_NONE_ARG = PytestRemovedIn8Warning(
     "Passing None to catch any warning has been deprecated, pass no arguments instead:\n"
-    " Replace pytest.warns(None) by simply pytest.warns()."
+    "Replace pytest.warns(None) by simply pytest.warns().\n"
+    "See https://docs.pytest.org/en/latest/deprecations.html"
+    "#using-pytest-warns-none"
+    " on asserting no warnings were emitted."
 )
 
 KEYWORD_MSG_ARG = UnformattedWarning(
diff --git a/testing/deprecated_test.py b/testing/deprecated_test.py
index c316b074c..79fcee620 100644
--- a/testing/deprecated_test.py
+++ b/testing/deprecated_test.py
@@ -138,8 +138,11 @@ def test_warns_none_is_deprecated():
     with pytest.warns(
         PytestDeprecationWarning,
         match=re.escape(
-            "Passing None to catch any warning has been deprecated, pass no arguments instead:\n "
-            "Replace pytest.warns(None) by simply pytest.warns()."
+            "Passing None to catch any warning has been deprecated, pass no arguments instead:\n"
+            "Replace pytest.warns(None) by simply pytest.warns().\n"
+            "See https://docs.pytest.org/en/latest/deprecations.html"
+            "#using-pytest-warns-none"
+            " on asserting no warnings were emitted."
         ),
     ):
         with pytest.warns(None):  # type: ignore[call-overload]