From 844a24bbb97af663ebf8dbeab4499acafe105943 Mon Sep 17 00:00:00 2001
From: Carl Meyer <carl@oddbird.net>
Date: Tue, 31 Jan 2012 20:36:11 +0000
Subject: Fixed #16921 -- Added assertHTMLEqual and assertHTMLNotEqual
 assertions, and converted Django tests to use them where appropriate. Thanks
 Greg Müllegger.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

git-svn-id: http://code.djangoproject.com/svn/django/trunk@17414 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/releases/1.4.txt   | 15 ++++++++++++
 docs/topics/testing.txt | 62 +++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 75 insertions(+), 2 deletions(-)

(limited to 'docs')

diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index f2c97f603a..cb0f01ed7d 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -475,6 +475,21 @@ Time zone support is enabled by default in new projects created with
 :djadmin:`startproject`. If you want to use this feature in an existing
 project, read the :ref:`migration guide <time-zones-migration-guide>`.
 
+HTML comparisons in tests
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :class:`~django.test.testcase.TestCase` base class now has some helpers to
+compare HTML without tripping over irrelevant differences in whitespace,
+argument quoting and ordering, and closing of self-closing tags. HTML can
+either be compared directly with the new
+:meth:`~django.test.testcase.TestCase.assertHTMLEqual` and
+:meth:`~django.test.testcase.TestCase.assertHTMLNotEqual` assertions, or use
+the ``html=True`` flag with
+:meth:`~django.test.testcase.TestCase.assertContains` and
+:meth:`~django.test.testcase.TestCase.assertNotContains` to test if the test
+client's response contains a given HTML fragment. See the :ref:`assertion
+documentation<assertions>` for more information.
+
 Minor features
 ~~~~~~~~~~~~~~
 
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index f0f0b445f9..ebc9f1ab28 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -1542,17 +1542,33 @@ your test suite.
         self.assertFieldOutput(EmailField, {'a@a.com': 'a@a.com'}, {'aaa': [u'Enter a valid e-mail address.']})
 
 
-.. method:: TestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='')
+.. method:: TestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)
 
     Asserts that a ``Response`` instance produced the given ``status_code`` and
     that ``text`` appears in the content of the response. If ``count`` is
     provided, ``text`` must occur exactly ``count`` times in the response.
 
-.. method:: TestCase.assertNotContains(response, text, status_code=200, msg_prefix='')
+    .. versionadded:: 1.4
+
+    Set ``html`` to ``True`` to handle ``text`` as HTML. The comparison with
+    the response content will be based on HTML semantics instead of
+    character-by-character equality. Whitespace is ignored in most cases,
+    attribute ordering is not significant. See
+    :func:`~TestCase.assertHTMLEqual` for more details.
+
+.. method:: TestCase.assertNotContains(response, text, status_code=200, msg_prefix='', html=False)
 
     Asserts that a ``Response`` instance produced the given ``status_code`` and
     that ``text`` does not appears in the content of the response.
 
+    .. versionadded:: 1.4
+
+    Set ``html`` to ``True`` to handle ``text`` as HTML. The comparison with
+    the response content will be based on HTML semantics instead of
+    character-by-character equality. Whitespace is ignored in most cases,
+    attribute ordering is not significant. See
+    :func:`~TestCase.assertHTMLEqual` for more details.
+
 .. method:: TestCase.assertFormError(response, form, field, errors, msg_prefix='')
 
     Asserts that a field on a form raises the provided list of errors when
@@ -1656,6 +1672,48 @@ your test suite.
             Person.objects.create(name="Aaron")
             Person.objects.create(name="Daniel")
 
+.. method:: TestCase.assertHTMLEqual(html1, html2, msg=None)
+
+    .. versionadded:: 1.4
+
+    Asserts that the strings ``html1`` and ``html2`` are equal. The comparison
+    is based on HTML semantics. The comparison takes following things into
+    account:
+
+    * Whitespace before and after HTML tags is ignored
+    * All types of whitespace are considered equivalent
+    * All open tags are closed implicitly, i.e. when a surrounding tag is
+      closed or the HTML document ends
+    * Empty tags are equivalent to their self-closing version
+    * The ordering of attributes of an HTML element is not significant
+    * Attributes without an argument are equal to attributes that equal in
+      name and value (see the examples)
+
+    The following examples are valid tests and don't raise any
+    ``AssertionError``::
+
+        self.assertHTMLEqual('<p>Hello <b>world!</p>',
+            '''<p>
+                Hello   <b>world! <b/>
+            </p>''')
+        self.assertHTMLEqual(
+            '<input type="checkbox" checked="checked" id="id_accept_terms" />',
+            '<input id="id_accept_terms" type='checkbox' checked>')
+
+    ``html1`` and ``html2`` must be valid HTML. An ``AssertionError`` will be
+    raised if one of them cannot be parsed.
+
+.. method:: TestCase.assertHTMLNotEqual(html1, html2, msg=None)
+
+    .. versionadded:: 1.4
+
+    Asserts that the strings ``html1`` and ``html2`` are *not* equal. The
+    comparison is based on HTML semantics. See
+    :func:`~TestCase.assertHTMLEqual` for details.
+
+    ``html1`` and ``html2`` must be valid HTML. An ``AssertionError`` will be
+    raised if one of them cannot be parsed.
+
 
 .. _topics-testing-email:
 
-- 
cgit v1.3