documentation doesn't explain why assertRaisesMessage is needed

[Sergey Fedoseev]

Apparently there is a good reason for assertRaisesMessage to exists, but documentation doesn't say a word if it's preferred over assertRaisesRegex. If it's really preferred, it's usage should be explicitly encouraged.

[Tim Graham]

It was added in #14503. Documentation says, "Similar to unittest’s assertRaisesRegex() with the difference that expected_message isn’t a regular expression." I guess with assertRaisesRegex you will have to call re.escape(expected_message) to ensure the message isn't treated as a regular expression. Should that point be noted? Another advantage from my perspective is that assertRaisesMessage won't need to change when dropping Python 2, unlike six.assertRaisesRegex (six -> self and removing self argument).

[Sergey Fedoseev]

I think that documentation should say that behavior of assertRaisesMessage is more straightforward and that assertRaisesRegex should be used only if regex is really needed.

[Tim Graham]

Is this explicit enough?

docs/topics/testing/tools.txt

@@ -1230 +1230 @@
 .. method:: SimpleTestCase.assertRaisesMessage(expected_exception, expected_message, callable_obj=None, *args, **kwargs)
 
     Asserts that execution of callable ``callable_obj`` raised the
-    ``expected_exception`` exception and that such exception has an
-    ``expected_message`` representation. 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.
+    ``expected_exception`` exception and that ``expected_message`` is in the
+    exception's representation. Any other 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.
 
 .. method:: SimpleTestCase.assertFieldOutput(fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value='')

[Sergey Fedoseev]

Replying to timgraham:

It's nice adjustment, but I thought that we should document somewhere that assertRaisesMessage is preferred for Django internal usage. Does this make sense?

[Tim Graham]

​PR as you requested.

[Tim Graham <timograham@…>]

In 77f50c9:

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

[Tim Graham <timograham@…>]

In c0d8d5f9:

[1.9.x] Fixed #25948 -- Added guidelines for SimpleTestCase.assertRaisesMessage() usage.

Backport of 77f50c9cfc8b33bf86394816cde183e656ba28cd from master