Deprecate the 'message' parameter of pytest.raises

Fix pytest-dev#3974

changelog/3974.deprecation.rst

@@ -0,0 +1,8 @@
+Passing the ``message`` parameter of ``pytest.raises`` now issues a ``DeprecationWarning``.
+
+It is a common mistake to think this parameter will match the exception message, while in fact
+it only serves to provide a custom message in case the ``pytest.raises`` check fails. To avoid this
+mistake and because it is believed to be little used, pytest is deprecating it without providing
+an alternative for the moment.
+
+If you have concerns about this, please comment on `issue #3974 <https://github.com/pytest-dev/pytest/issues/3974>`__.

doc/en/deprecations.rst

@@ -14,6 +14,19 @@ Below is a complete list of all pytest features which are considered deprecated.
 :class:`_pytest.warning_types.PytestWarning` or subclasses, which can be filtered using
 :ref:`standard warning filters <warnings>`.
 
+``"message"`` parameter of ``pytest.raises``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 4.1
+
+It is a common mistake to think this parameter will match the exception message, while in fact
+it only serves to provide a custom message in case the ``pytest.raises`` check fails. To avoid this
+mistake and because it is believed to be little used, pytest is deprecating it without providing
+an alternative for the moment.
+
+If you have concerns about this, please comment on `issue #3974 <https://github.com/pytest-dev/pytest/issues/3974>`__.
+
+
 ``pytest.config`` global
 ~~~~~~~~~~~~~~~~~~~~~~~~
 

src/_pytest/deprecated.py

@@ -51,6 +51,13 @@
     "getfuncargvalue is deprecated, use getfixturevalue"
 )
 
+RAISES_MESSAGE_PARAMETER = PytestDeprecationWarning(
+    "The 'message' parameter is deprecated.\n"
+    "(did you mean to use `match='some regex'` to check the exception message?)\n"
+    "Please comment on https://github.com/pytest-dev/pytest/issues/3974 "
+    "if you have concerns about removal of this parameter."
+)
+
 RESULT_LOG = PytestDeprecationWarning(
     "--result-log is deprecated and scheduled for removal in pytest 5.0.\n"
     "See https://docs.pytest.org/en/latest/deprecations.html#result-log-result-log for more information."

src/_pytest/python_api.py

@@ -13,11 +13,11 @@
 from six.moves import zip
 
 import _pytest._code
+from _pytest import deprecated
 from _pytest.compat import isclass
 from _pytest.compat import Mapping
 from _pytest.compat import Sequence
 from _pytest.compat import STRING_TYPES
-from _pytest.deprecated import RAISES_EXEC
 from _pytest.outcomes import fail
 
 BASE_TYPE = (type, STRING_TYPES)
@@ -660,6 +660,7 @@ def raises(expected_exception, *args, **kwargs):
     if not args:
         if "message" in kwargs:
             message = kwargs.pop("message")
+            warnings.warn(deprecated.RAISES_MESSAGE_PARAMETER, stacklevel=2)
         if "match" in kwargs:
             match_expr = kwargs.pop("match")
         if kwargs:
@@ -668,7 +669,7 @@ def raises(expected_exception, *args, **kwargs):
             raise TypeError(msg)
         return RaisesContext(expected_exception, message, match_expr)
     elif isinstance(args[0], str):
-        warnings.warn(RAISES_EXEC, stacklevel=2)
+        warnings.warn(deprecated.RAISES_EXEC, stacklevel=2)
         code, = args
         assert isinstance(code, str)
         frame = sys._getframe(1)

testing/deprecated_test.py

@@ -136,6 +136,12 @@ def test_func(pytestconfig):
     )
 
 
+def test_raises_message_argument_deprecated():
+    with pytest.warns(pytest.PytestDeprecationWarning):
+        with pytest.raises(RuntimeError, message="foobar"):
+            raise RuntimeError
+
+
 def test_pytest_plugins_in_non_top_level_conftest_deprecated(testdir):
     from _pytest.deprecated import PYTEST_PLUGINS_FROM_NON_TOP_LEVEL_CONFTEST
 

testing/python/raises.py

@@ -121,8 +121,9 @@ def test_no_raise_message(self):
     def test_custom_raise_message(self):
         message = "TEST_MESSAGE"
         try:
-            with pytest.raises(ValueError, message=message):
-                pass
+            with pytest.warns(PytestDeprecationWarning):
+                with pytest.raises(ValueError, message=message):
+                    pass
         except pytest.raises.Exception as e:
             assert e.msg == message
         else:

testing/test_pytester.py

@@ -280,7 +280,7 @@ def test_assert_outcomes_after_pytest_error(testdir):
     testdir.makepyfile("def test_foo(): assert True")
 
     result = testdir.runpytest("--unexpected-argument")
-    with pytest.raises(ValueError, message="Pytest terminal report not found"):
+    with pytest.raises(ValueError, match="Pytest terminal report not found"):
         result.assert_outcomes(passed=0)
 
 

tox.ini

@@ -194,6 +194,7 @@ norecursedirs = testing/example_scripts
 xfail_strict=true
 filterwarnings =
     error
+    ignore:The 'message' parameter is deprecated:pytest.PytestDeprecationWarning
     ignore:yield tests are deprecated, and scheduled to be removed in pytest 4.0:pytest.RemovedInPytest4Warning
     ignore:Metafunc.addcall is deprecated and scheduled to be removed in pytest 4.0:pytest.RemovedInPytest4Warning
     ignore::pytest.RemovedInPytest4Warning