Fixed #25948 -- Added guidelines for SimpleTestCase.assertRaisesMessage() usage.

2 files changed, 9 insertions, 3 deletions

diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt
index ed07bd49a3..bdf1c4bb45 100644
--- a/docs/internals/contributing/writing-code/coding-style.txt
+++ b/docs/internals/contributing/writing-code/coding-style.txt
@@ -45,6 +45,12 @@ Python style
           """
           ...
 
+* In tests, use :meth:`~django.test.SimpleTestCase.assertRaisesMessage` instead
+  of :meth:`~unittest.TestCase.assertRaises` so you can check the exception
+  message. Use :meth:`~unittest.TestCase.assertRaisesRegex`
+  (``six.assertRaisesRegex()`` as long as we support Python 2) only if you need
+  to use regular expression matching.
+
 Imports
 -------
 
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 1eeb68e7d3..f9e302a0c1 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -1345,9 +1345,9 @@ your test suite.
 
     Asserts that execution of ``callable`` raises ``expected_exception`` and
     that ``expected_message`` is found in the exception's message. Any other
-    outcome is reported as a failure. Similar to unittest's
-    :meth:`~unittest.TestCase.assertRaisesRegex` with the difference that
-    ``expected_message`` isn't a regular expression.
+    outcome is reported as a failure. It's a simpler version of
+    :meth:`unittest.TestCase.assertRaisesRegex` with the difference that
+    ``expected_message`` isn't treated as a regular expression.
 
     If only the ``expected_exception`` and ``expected_message`` parameters are
     given, returns a context manager so that the code being tested can be