Allow using warnings.warn() with Warnings

`pytest.warns()` now allows using `warnings.warn()` with a `Warning`
instance, as is required by Python, with one exception. If the warning
used is a `UserWarning` that was created by passing it arguments and the
first argument was not a `str` then `pytest.raises()` still considers
that an error. This is because if an invalid type was used in
`warnings.warn()` then Python creates a `UserWarning` anyways and it
becomes impossible for `pytest` to figure out if that was done
automatically or not.

Author: eerovaher

AUTHORS

@@ -127,6 +127,7 @@ Edison Gustavo Muenz
 Edoardo Batini
 Edson Tadeu M. Manoel
 Eduardo Schettino
+Eero Vaher
 Eli Boyarski
 Elizaveta Shashkova
 Éloi Rivard

changelog/10865.improvement.rst

@@ -1,2 +1,8 @@
-:func:`pytest.warns` now validates that warning object's ``message`` is of type  `str` -- currently in Python it is possible to pass other types than `str` when creating `Warning` instances, however this causes an exception when :func:`warnings.filterwarnings` is used to filter those warnings. See `CPython #103577 <https://github.com/python/cpython/issues/103577>`__ for a discussion.
-While this can be considered a bug in CPython, we decided to put guards in pytest as the error message produced without this check in place is confusing.
+:func:`pytest.warns` now validates that :func:`warnings.warn` was called with a
+`str` or a `Warning`.
+Currently in Python it is possible to use other types, however this causes an
+exception when :func:`warnings.filterwarnings` is used to filter those warnings
+(see `CPython #103577 <https://github.com/python/cpython/issues/103577>`__ for
+a discussion).
+While this can be considered a bug in CPython, we decided to put guards in
+pytest as the error message produced without this check in place is confusing.

src/_pytest/recwarn.py

@@ -336,7 +336,18 @@ def found_str():
 
     @staticmethod
     def _validate_message(wrn: Any) -> None:
+        if isinstance(wrn.message, Warning) and type(wrn.message) is not UserWarning:
+            # If the warning was of an incorrect type then Python creates a UserWarning.
+            # Any other warning must have been specified explicitly.
+            return
+        if not wrn.message.args:
+            # UserWarning() without arguments must have been specified explicitly.
+            return
         if not isinstance(msg := wrn.message.args[0], str):
+            # It is possible that UserWarning was explicitly specified, but its
+            # first argument was not a string, but that case can't be
+            # distinguished from an invalid type.
             raise TypeError(
-                f"Warning message must be str, got {msg!r} (type {type(msg).__name__})"
+                "Warning must be str or Warning, got "
+                f"{msg!r} (type {type(msg).__name__})"
             )

testing/test_recwarn.py

@@ -3,6 +3,7 @@
 from typing import List
 from typing import Optional
 from typing import Type
+from typing import Union
 import warnings
 
 from _pytest.pytester import Pytester
@@ -483,7 +484,7 @@ def test_catch_warning_within_raise(self) -> None:
 def test_raise_type_error_on_invalid_warning() -> None:
     """Check pytest.warns validates warning messages are strings (#10865) or
     Warning instances (#11959)."""
-    with pytest.raises(TypeError, match="Warning message must be str"):
+    with pytest.raises(TypeError, match="Warning must be str or Warning"):
         with pytest.warns(UserWarning):
             warnings.warn(1)  # type: ignore
 
@@ -496,7 +497,7 @@ def test_raise_type_error_on_invalid_warning() -> None:
         pytest.param(Warning(), id="Warning"),
     ],
 )
-def test_no_raise_type_error_on_valid_warning(message: str | Warning) -> None:
+def test_no_raise_type_error_on_valid_warning(message: Union[str, Warning]) -> None:
     """Check pytest.warns validates warning messages are strings (#10865) or
     Warning instances (#11959)."""
     with pytest.warns(Warning):