From e69f04e3ce4483596d63394053abe9669bf38b8d Mon Sep 17 00:00:00 2001
From: Olga Matoula <olgamatoula@gmail.com>
Date: Wed, 12 Jan 2022 17:42:15 +0000
Subject: [PATCH] Add new section for common warnings use cases

---
 doc/en/deprecations.rst            | 23 +----------------------
 doc/en/how-to/capture-warnings.rst | 26 ++++++++++++++++++++++++++
 src/_pytest/deprecated.py          |  9 ++++-----
 testing/deprecated_test.py         |  9 ++++-----
 4 files changed, 35 insertions(+), 32 deletions(-)

diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst
index 455a252c7..358967fae 100644
--- a/doc/en/deprecations.rst
+++ b/doc/en/deprecations.rst
@@ -225,28 +225,7 @@ Using ``pytest.warns(None)``
 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
+See https://docs.pytest.org/en/latest/how-to/capture-warnings.html#additional-use-cases-of-warnings-in-tests for use cases.
 
 The ``--strict`` command-line option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst
index 7e877b4d3..5ae59b7f8 100644
--- a/doc/en/how-to/capture-warnings.rst
+++ b/doc/en/how-to/capture-warnings.rst
@@ -300,6 +300,32 @@ filter at the end of the test, so no global state is leaked.
 
 .. _recwarn:
 
+Additional use cases of warnings in tests
+-----------------------------------------
+
+Here are some use cases involving warnings that often come up in tests, and suggestions on how to deal with them:
+
+- To ensure that **any** warning is emitted, use:
+
+.. code-block:: python
+
+    with pytest.warns():
+        pass
+
+-  To ensure that **no** warnings are emitted, use:
+
+.. code-block:: python
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+
+- To suppress warnings, use:
+
+.. code-block:: python
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore")
+
 Recording warnings
 ------------------
 
diff --git a/src/_pytest/deprecated.py b/src/_pytest/deprecated.py
index 2f7ab5bde..55a09d496 100644
--- a/src/_pytest/deprecated.py
+++ b/src/_pytest/deprecated.py
@@ -88,11 +88,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().\n"
-    "See https://docs.pytest.org/en/latest/deprecations.html"
-    "#using-pytest-warns-none"
-    " on asserting no warnings were emitted."
+    "Passing None has been deprecated.\n"
+    "See https://docs.pytest.org/en/latest/how-to/capture-warnings.html"
+    "#additional-use-cases-of-warnings-in-tests"
+    " for alternativesin common use cases."
 )
 
 KEYWORD_MSG_ARG = UnformattedWarning(
diff --git a/testing/deprecated_test.py b/testing/deprecated_test.py
index 79fcee620..2bebfe25f 100644
--- a/testing/deprecated_test.py
+++ b/testing/deprecated_test.py
@@ -138,11 +138,10 @@ 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().\n"
-            "See https://docs.pytest.org/en/latest/deprecations.html"
-            "#using-pytest-warns-none"
-            " on asserting no warnings were emitted."
+            "Passing None has been deprecated.\n"
+            "See https://docs.pytest.org/en/latest/how-to/capture-warnings.html"
+            "#additional-use-cases-of-warnings-in-tests"
+            " for alternativesin common use cases."
         ),
     ):
         with pytest.warns(None):  # type: ignore[call-overload]