Fixed #33348 -- Changed SimpleTestCase.assertFormError()/assertFormsetErrors() to take form/formset.

Instead of taking a response object and a context name for
the form/formset, the two methods now take the object directly.

1 files changed, 45 insertions, 27 deletions

diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index c6923c6c87..836dab54e4 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -1473,47 +1473,65 @@ your test suite.
 
         self.assertFieldOutput(EmailField, {'a@a.com': 'a@a.com'}, {'aaa': ['Enter a valid email address.']})
 
-.. method:: SimpleTestCase.assertFormError(response, form, field, errors, msg_prefix='')
+.. method:: SimpleTestCase.assertFormError(form, field, errors, msg_prefix='')
 
-    Asserts that a field on a form raises the provided list of errors when
-    rendered on the form.
+    Asserts that a field on a form raises the provided list of errors.
 
-    ``response`` must be a response instance returned by the
-    :class:`test client <django.test.Response>`.
+    ``form`` is a ``Form`` instance. The form must be
+    :ref:`bound <ref-forms-api-bound-unbound>` but not necessarily
+    validated (``assertFormError()`` will automatically call ``full_clean()``
+    on the form).
+
+    ``field`` is the name of the field on the form to check. To check the form's
+    :meth:`non-field errors <django.forms.Form.non_field_errors>`, use
+    ``field=None``.
+
+    ``errors`` is a list of all the error strings that the field is expected to
+    have. You can also pass a single error string if you only expect one error
+    which means that ``errors='error message'`` is the same as
+    ``errors=['error message']``.
 
-    ``form`` is the name the ``Form`` instance was given in the template
-    context of the response.
+    .. versionchanged:: 4.1
 
-    ``field`` is the name of the field on the form to check. If ``field``
-    has a value of ``None``, non-field errors (errors you can access via
-    :meth:`form.non_field_errors() <django.forms.Form.non_field_errors>`) will
-    be checked.
+        In older versions, using an empty error list with ``assertFormError()``
+        would always pass, regardless of whether the field had any errors or
+        not. Starting from Django 4.1, using ``errors=[]`` will only pass if
+        the field actually has no errors.
 
-    ``errors`` is an error string, or a list of error strings, that are
-    expected as a result of form validation.
+        Django 4.1 also changed the behavior of ``assertFormError()`` when a
+        field has multiple errors. In older versions, if a field had multiple
+        errors and you checked for only some of them, the test would pass.
+        Starting from Django 4.1, the error list must be an exact match to the
+        field's actual errors.
 
-.. method:: SimpleTestCase.assertFormsetError(response, formset, form_index, field, errors, msg_prefix='')
+    .. deprecated:: 4.1
+
+        Support for passing a response object and a form name to
+        ``assertFormError()`` is deprecated and will be removed in Django 5.0.
+        Use the form instance directly instead.
+
+.. method:: SimpleTestCase.assertFormsetError(formset, form_index, field, errors, msg_prefix='')
 
     Asserts that the ``formset`` raises the provided list of errors when
     rendered.
 
-    ``response`` must be a response instance returned by the
-    :class:`test client <django.test.Response>`.
+    ``formset`` is a ``Formset`` instance. The formset must be bound but not
+    necessarily validated (``assertFormsetError()`` will automatically call the
+    ``full_clean()`` on the formset).
 
-    ``formset`` is the name the ``Formset`` instance was given in the template
-    context of the response.
+    ``form_index`` is the number of the form within the ``Formset`` (starting
+    from 0). Use ``form_index=None`` to check the formset's non-form errors,
+    i.e. the errors you get when calling ``formset.non_form_errors()``. In that
+    case you must also use ``field=None``.
 
-    ``form_index`` is the number of the form within the ``Formset``.  If
-    ``form_index`` has a value of ``None``, non-form errors (errors you can
-    access via ``formset.non_form_errors()``) will be checked.
+    ``field`` and ``errors`` have the same meaning as the parameters to
+    ``assertFormError()``.
 
-    ``field`` is the name of the field on the form to check. If ``field``
-    has a value of ``None``, non-field errors (errors you can access via
-    :meth:`form.non_field_errors() <django.forms.Form.non_field_errors>`) will
-    be checked.
+    .. deprecated:: 4.1
 
-    ``errors`` is an error string, or a list of error strings, that are
-    expected as a result of form validation.
+        Support for passing a response object and a formset name to
+        ``assertFormsetError()`` is deprecated and will be removed in Django
+        5.0. Use the formset instance directly instead.
 
 .. method:: SimpleTestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)