Refactor: Improve clarity of 'expected exception' error messages

changelog/13861.improvement.rst

@@ -0,0 +1,2 @@
+Better sentence structure in a test's expected error message. Previously, the error message would be "expected exception must be <expected>, but got <actual>". Now, it is "Expected <expected>, but got <actual>".
+This PR addresses the TODO comment in `testing/python/raises_group.py:49` and widens the scope to all expected error messages in both `testing/python/raises.py` and `testing/python/raises_group.py`.

src/_pytest/raises.py

@@ -464,11 +464,11 @@ def _parse_exc(
                     f"with `RaisesGroup`."
                 )
         # unclear if the Type/ValueError distinction is even helpful here
-        msg = f"expected exception must be {expected}, not "
+        msg = f"Expected {expected}, but got "
         if isinstance(exc, type):  # type: ignore[unreachable]
             raise ValueError(msg + f"{exc.__name__!r}")
         if isinstance(exc, BaseException):  # type: ignore[unreachable]
-            raise TypeError(msg + f"an exception instance ({type(exc).__name__})")
+            raise TypeError(msg + f"an exception instance: {type(exc).__name__}")
         raise TypeError(msg + repr(type(exc).__name__))
 
     @property
@@ -1036,7 +1036,7 @@ def _parse_excgroup(
             return exc
         elif isinstance(exc, tuple):
             raise TypeError(
-                f"expected exception must be {expected}, not {type(exc).__name__!r}.\n"
+                f"Expected {expected}, but got {type(exc).__name__!r}.\n"
                 "RaisesGroup does not support tuples of exception types when expecting one of "
                 "several possible exception types like RaisesExc.\n"
                 "If you meant to expect a group with multiple exceptions, list them as separate arguments."

testing/python/raises.py

@@ -367,9 +367,7 @@ def test_raises_context_manager_with_kwargs(self):
     def test_expected_exception_is_not_a_baseexception(self) -> None:
         with pytest.raises(
             TypeError,
-            match=wrap_escape(
-                "expected exception must be a BaseException type, not 'str'"
-            ),
+            match=wrap_escape("Expected a BaseException type, but got 'str'"),
         ):
             with pytest.raises("hello"):  # type: ignore[call-overload]
                 pass  # pragma: no cover
@@ -380,17 +378,15 @@ class NotAnException:
         with pytest.raises(
             ValueError,
             match=wrap_escape(
-                "expected exception must be a BaseException type, not 'NotAnException'"
+                "Expected a BaseException type, but got 'NotAnException'"
             ),
         ):
             with pytest.raises(NotAnException):  # type: ignore[type-var]
                 pass  # pragma: no cover
 
         with pytest.raises(
             TypeError,
-            match=wrap_escape(
-                "expected exception must be a BaseException type, not 'str'"
-            ),
+            match=wrap_escape("Expected a BaseException type, but got 'str'"),
         ):
             with pytest.raises(("hello", NotAnException)):  # type: ignore[arg-type]
                 pass  # pragma: no cover

testing/python/raises_group.py

@@ -36,19 +36,18 @@ def fails_raises_group(msg: str, add_prefix: bool = True) -> RaisesExc[Failed]:
 def test_raises_group() -> None:
     with pytest.raises(
         TypeError,
-        match=wrap_escape("expected exception must be a BaseException type, not 'int'"),
+        match=wrap_escape("Expected a BaseException type, but got 'int'"),
     ):
         RaisesExc(5)  # type: ignore[call-overload]
     with pytest.raises(
         ValueError,
-        match=wrap_escape("expected exception must be a BaseException type, not 'int'"),
+        match=wrap_escape("Expected a BaseException type, but got 'int'"),
     ):
         RaisesExc(int)  # type: ignore[type-var]
     with pytest.raises(
         TypeError,
-        # TODO: bad sentence structure
         match=wrap_escape(
-            "expected exception must be a BaseException type, RaisesExc, or RaisesGroup, not an exception instance (ValueError)",
+            "Expected a BaseException type, RaisesExc, or RaisesGroup, but got an exception instance: ValueError",
         ),
     ):
         RaisesGroup(ValueError())  # type: ignore[call-overload]
@@ -1078,9 +1077,7 @@ def test_raisesexc() -> None:
         RaisesExc()  # type: ignore[call-overload]
     with pytest.raises(
         ValueError,
-        match=wrap_escape(
-            "expected exception must be a BaseException type, not 'object'"
-        ),
+        match=wrap_escape("Expected a BaseException type, but got 'object'"),
     ):
         RaisesExc(object)  # type: ignore[type-var]
 
@@ -1351,7 +1348,7 @@ def test_tuples() -> None:
     with pytest.raises(
         TypeError,
         match=wrap_escape(
-            "expected exception must be a BaseException type, RaisesExc, or RaisesGroup, not 'tuple'.\n"
+            "Expected a BaseException type, RaisesExc, or RaisesGroup, but got 'tuple'.\n"
             "RaisesGroup does not support tuples of exception types when expecting one of "
             "several possible exception types like RaisesExc.\n"
             "If you meant to expect a group with multiple exceptions, list them as separate arguments."