FIXUP: initial version of new docs

doc/en/assert.txt

@@ -113,42 +113,16 @@ exceptions your own code is deliberately raising, whereas using
 like documenting unfixed bugs (where the test describes what "should" happen)
 or bugs in dependencies.
 
+
+.. _`assertwarns`:
+
 Assertions about expected warnings
 -----------------------------------------
 
 .. versionadded:: 2.8
 
-You can also check that code raises a particular warning using ``pytest.warns``,
-which works in a similar manner to ``pytest.raises`` (see above)::
-
-    import warnings
-    import pytest
-
-    def test_warning():
-        with pytest.warns(UserWarning):
-            warnings.warn("my warning", UserWarning)
-
-The test will fail if the warning in question is not raised.
-
-You can also call ``pytest.warns`` on a function or code string::
-
-    pytest.warns(expected_warning, func, *args, **kwargs)
-    pytest.warns(expected_warning, "func(*args, **kwargs)")
-
-The function also returns a list of all raised warnings (as
-``warnings.WarningMessage`` objects), which you can query for
-additional information::
-
-    with pytest.warns(RuntimeWarning) as record:
-        warnings.warn("another warning", RuntimeWarning)
-
-    # check that only one warning was raised
-    assert len(record) == 1
-    # check that the message matches
-    assert record[0].message.args[0] == "another warning"
-
-Alternatively, you can examine raised warnings in detail using the
-:ref:`recwarn <recwarn>` function argument.
+You can check that code raises a particular warning using
+:ref:`pytest.warns <warns>`.
 
 
 .. _newreport:

doc/en/recwarn.txt

@@ -1,27 +1,80 @@
 
-Asserting deprecation and other warnings
+Asserting Warnings
 =====================================================
 
+.. _warns:
+
+Asserting warnings with the warns function
+-----------------------------------------------
+
+.. versionadded:: 2.8
+
+You can check that code raises a particular warning using ``pytest.warns``,
+which works in a similar manner to :ref:`raises <assertraises>`::
+
+    import warnings
+    import pytest
+
+    def test_warning():
+        with pytest.warns(UserWarning):
+            warnings.warn("my warning", UserWarning)
+
+The test will fail if the warning in question is not raised.
+
+You can also call ``pytest.warns`` on a function or code string::
+
+    pytest.warns(expected_warning, func, *args, **kwargs)
+    pytest.warns(expected_warning, "func(*args, **kwargs)")
+
+The function also returns a list of all raised warnings (as
+``warnings.WarningMessage`` objects), which you can query for
+additional information::
+
+    with pytest.warns(RuntimeWarning) as record:
+        warnings.warn("another warning", RuntimeWarning)
+
+    # check that only one warning was raised
+    assert len(record) == 1
+    # check that the message matches
+    assert record[0].message.args[0] == "another warning"
+
+Alternatively, you can examine raised warnings in detail using the
+:ref:`recwarn <recwarn>` function argument (see below).
+
 .. _recwarn:
 
-The recwarn function argument
-------------------------------------
+Recording warnings
+------------------------
+
+You can record raised warnings either using ``pytest.warns`` or with
+the ``recwarn`` function argument.
+
+To record with ``pytest.warns`` without asserting anything about the warnings,
+pass ``None`` as the expected warning type::
+
+    with pytest.warns(None) as record:
+        warnings.warn("user", UserWarning)
+        warnings.warn("runtime", RuntimeWarning)
+
+    assert len(record) == 2
+    assert str(record[0].message) == "user"
+    assert str(record[1].message) == "runtime"
 
-You can use the ``recwarn`` funcarg to assert that code triggers
-warnings through the Python warnings system. Here is a simple
-self-contained test::
+The ``recwarn`` function argument will record warnings for the whole function::
+
+    import warnings
 
-    # 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)
+        warnings.warn("hello", UserWarning)
+        assert len(recwarn) == 1
+        w = recwarn.pop(UserWarning)
+        assert issubclass(w.category, UserWarning)
+        assert str(w.message) == "hello"
         assert w.filename
         assert w.lineno
 
-The ``recwarn`` function argument provides these methods:
+Both ``recwarn`` and ``pytest.warns`` return the same interface for recorded
+warnings, which provides these methods:
 
 .. method:: pop(category=None)
 
@@ -44,3 +97,17 @@ that a certain function call triggers a ``DeprecationWarning``::
 
     def test_global():
         pytest.deprecated_call(myfunction, 17)
+
+By default, deprecation warnings will not be caught when using ``pytest.warns``
+or ``recwarn``, since the default Python warnings filters hide
+DeprecationWarnings. If you wish to record them in your own code, use the
+command ``warnings.simplefilter('always')``::
+
+    import warnings
+    import pytest
+
+    def test_deprecation(recwarn):
+        warnings.simplefilter('always')
+        warnings.warn("deprecated", DeprecationWarning)
+        assert len(recwarn) == 1
+        assert recwarn.pop(DeprecationWarning)