diff --git a/changelog/9291.doc.rst b/changelog/9291.doc.rst new file mode 100644 index 00000000000..fad8467dc90 --- /dev/null +++ b/changelog/9291.doc.rst @@ -0,0 +1 @@ +Update documentation on how :func:`pytest.warns` affects :class:`DeprecationWarning`. diff --git a/doc/en/how-to/capture-warnings.rst b/doc/en/how-to/capture-warnings.rst index ad5c1f3c3df..91565002ccc 100644 --- a/doc/en/how-to/capture-warnings.rst +++ b/doc/en/how-to/capture-warnings.rst @@ -42,6 +42,8 @@ Running pytest now produces this output: -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html ======================= 1 passed, 1 warning in 0.12s ======================= +.. _`controlling-warnings`: + Controlling warnings -------------------- @@ -176,11 +178,14 @@ using an external system. DeprecationWarning and PendingDeprecationWarning ------------------------------------------------ - By default pytest will display ``DeprecationWarning`` and ``PendingDeprecationWarning`` warnings from user code and third-party libraries, as recommended by :pep:`565`. This helps users keep their code modern and avoid breakages when deprecated warnings are effectively removed. +However, in the specific case where users capture any type of warnings in their test, either with +:func:`pytest.warns`, :func:`pytest.deprecated_call` or using the :ref:`recwarn ` fixture, +no warning will be displayed at all. + Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over (such as third-party libraries), in which case you might use the warning filters options (ini or marks) to ignore those warnings. @@ -197,6 +202,9 @@ For example: This will ignore all warnings of type ``DeprecationWarning`` where the start of the message matches the regular expression ``".*U.*mode is deprecated"``. +See :ref:`@pytest.mark.filterwarnings ` and +:ref:`Controlling warnings ` for more examples. + .. note:: If warnings are configured at the interpreter level, using @@ -245,10 +253,10 @@ when called with a ``17`` argument. Asserting warnings with the warns function ------------------------------------------ - - You can check that code raises a particular warning using :func:`pytest.warns`, -which works in a similar manner to :ref:`raises `: +which works in a similar manner to :ref:`raises ` (except that +:ref:`raises ` does not capture all exceptions, only the +``expected_exception``): .. code-block:: python @@ -261,8 +269,8 @@ which works in a similar manner to :ref:`raises `: with pytest.warns(UserWarning): warnings.warn("my warning", UserWarning) -The test will fail if the warning in question is not raised. The keyword -argument ``match`` to assert that the exception matches a text or regex:: +The test will fail if the warning in question is not raised. Use the keyword +argument ``match`` to assert that the warning matches a text or regex:: >>> with warns(UserWarning, match='must be 0 or None'): ... warnings.warn("value must be 0 or None", UserWarning) @@ -359,20 +367,32 @@ 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 **at least one** warning is emitted, use: +- To ensure that **at least one** of the indicated warnings is issued, use: .. code-block:: python - with pytest.warns(): + def test_warning(): + with pytest.warns((RuntimeWarning, UserWarning)): + ... + +- To ensure that **only** certain warnings are issued, use: + +.. code-block:: python + + def test_warning(recwarn): ... + assert len(recwarn) == 1 + user_warning = recwarn.pop(UserWarning) + assert issubclass(user_warning.category, UserWarning) - To ensure that **no** warnings are emitted, use: .. code-block:: python - with warnings.catch_warnings(): - warnings.simplefilter("error") - ... + def test_warning(): + with warnings.catch_warnings(): + warnings.simplefilter("error") + ... - To suppress warnings, use: diff --git a/src/_pytest/recwarn.py b/src/_pytest/recwarn.py index 9c6e7e91daf..0cf860f6ae2 100644 --- a/src/_pytest/recwarn.py +++ b/src/_pytest/recwarn.py @@ -110,15 +110,15 @@ def warns( ) -> Union["WarningsChecker", Any]: r"""Assert that code raises a particular class of warning. - Specifically, the parameter ``expected_warning`` can be a warning class or - sequence of warning classes, and the code inside the ``with`` block must issue a warning of that class or - classes. + Specifically, the parameter ``expected_warning`` can be a warning class or sequence + of warning classes, and the code inside the ``with`` block must issue at least one + warning of that class or classes. - This helper produces a list of :class:`warnings.WarningMessage` objects, - one for each warning raised. + This helper produces a list of :class:`warnings.WarningMessage` objects, one for + each warning raised (regardless of whether it is an ``expected_warning`` or not). - This function can be used as a context manager, or any of the other ways - :func:`pytest.raises` can be used:: + This function can be used as a context manager, which will capture all the raised + warnings inside it:: >>> import pytest >>> with pytest.warns(RuntimeWarning): @@ -139,6 +139,14 @@ def warns( ... Failed: DID NOT WARN. No warnings of type ...UserWarning... were emitted... + **Using with** ``pytest.mark.parametrize`` + + When using :ref:`pytest.mark.parametrize ref` it is possible to parametrize tests + such that some runs raise a warning and others do not. + + This could be achieved in the same way as with exceptions, see + :ref:`parametrizing_conditional_raising` for an example. + """ __tracebackhide__ = True if not args: