Docs: Note that ResourceWarning is often delayed and needs an extra filter

doc/en/how-to/capture-warnings.rst

@@ -593,3 +593,23 @@ enough number of frames (say ``20``, but that number is application dependent).
 
 For more information, consult the `Python Development Mode <https://docs.python.org/3/library/devmode.html>`__
 section in the Python documentation.
+
+Furthermore, a ``ResourceWarning`` is a special case in Python, because it is usually not triggered directly
+by the code causing the leak (like an unclosed file), but by the Python interpreter during
+garbage collection.
+
+Because of this, trying to use ``@pytest.mark.filterwarnings("error::ResourceWarning")`` or
+similar filters to turn them into errors will not work as expected because the warning is raised later and
+caught by pytest internally, emitting a :class:`pytest.PytestUnraisableExceptionWarning`.
+
+To properly catch and filter these, you must also add a filter for the unraisable exception:
+
+.. code-block:: python
+
+    import pytest
+
+
+    @pytest.mark.filterwarnings("error::ResourceWarning")
+    @pytest.mark.filterwarnings("error::pytest.PytestUnraisableExceptionWarning")
+    def test_resource_warning():
+        open("/dev/null")

doc/en/reference/reference.rst

@@ -214,7 +214,7 @@ pytest.mark.skip
 
 Unconditionally skip a test function.
 
-.. py:function:: pytest.mark.skip(reason=None)
+.. py:function:: pytest.mark.skip(reason="unconditional skip")
 
     :keyword str reason: Reason why the test function is being skipped.
 
@@ -266,7 +266,7 @@ pytest.mark.xfail
 
 Marks a test function as *expected to fail*.
 
-.. py:function:: pytest.mark.xfail(condition=False, *, reason=None, raises=None, run=True, strict=strict_xfail)
+.. py:function:: pytest.mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=strict_xfail)
 
     :keyword Union[bool, str] condition:
         Condition for marking the test function as xfail (``True/False`` or a
@@ -277,7 +277,7 @@ Marks a test function as *expected to fail*.
     :keyword raises:
         Exception class (or tuple of classes) expected to be raised by the test function; other exceptions will fail the test.
         Note that subclasses of the classes passed will also result in a match (similar to how the ``except`` statement works).
-    :type raises: Type[:py:exc:`Exception`]
+    :type raises: Type[:py:exc:`Exception`] | Tuple[Type[:py:exc:`Exception`], ...] | None
 
     :keyword bool run:
         Whether the test function should actually be executed. If ``False``, the function will always xfail and will
@@ -765,6 +765,17 @@ items, delete or otherwise amend the test items:
 .. hook:: pytest_collection_finish
 .. autofunction:: pytest_collection_finish
 
+.. hook:: pytest_collectstart
+.. autofunction:: pytest_collectstart
+.. hook:: pytest_make_collect_report
+.. autofunction:: pytest_make_collect_report
+.. hook:: pytest_itemcollected
+.. autofunction:: pytest_itemcollected
+.. hook:: pytest_collectreport
+.. autofunction:: pytest_collectreport
+.. hook:: pytest_deselected
+.. autofunction:: pytest_deselected
+
 Test running (runtest) hooks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -801,16 +812,6 @@ Reporting hooks
 
 Session related reporting hooks:
 
-.. hook:: pytest_collectstart
-.. autofunction:: pytest_collectstart
-.. hook:: pytest_make_collect_report
-.. autofunction:: pytest_make_collect_report
-.. hook:: pytest_itemcollected
-.. autofunction:: pytest_itemcollected
-.. hook:: pytest_collectreport
-.. autofunction:: pytest_collectreport
-.. hook:: pytest_deselected
-.. autofunction:: pytest_deselected
 .. hook:: pytest_report_header
 .. autofunction:: pytest_report_header
 .. hook:: pytest_report_collectionfinish