Renaming assertXmlEquivalent to assertXmlEquivalentOutputs, and update documentation for clarity purpose. And up to 0.2.0.

Author: Exirel

doc/conf.py

@@ -48,13 +48,13 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1-dev'
+release = '0.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

doc/index.rst

@@ -413,64 +413,6 @@ XPath expression assertions
       # ...
 
 
-XML documents comparison assertion
-----------------------------------
-
-.. py:method:: XmlTestMixin.assertXmlEquivalent(got, expect)
-
-   :param got: XML as text or Element node
-   :param expect: XML as text
-
-   Asserts both XML are equivalent. The comparison ignores spaces within nodes
-   and namespaces - if any - may be associated to diffrerent prefixes.
-
-   If a difference is found, a :class:`AssertionError` is raised. You can have
-   the detailed mismatch in ``str(exc)``, ``exc`` being the raised exception.
-
-   .. rubric:: Example
-
-   ::
-
-      # ...
-
-      def test_custom_test(self):
-          # Same XML (with different spacings placements and attrs order)
-          got = b"""<?xml version="1.0" encoding="UTF-8" ?>
-          <root>
-              <tag foo="bar" bar="foo">foo</tag>
-          </root>"""
-          got_root = self.assertXmlDocument(got)
-          expected = b"""<?xml version="1.0" encoding="UTF-8" ?>
-          <root><tag bar="foo" foo="bar"> foo </tag></root>"""
-
-          self.assertXmlEquivalent(got, expected)
-          self.assertXmlEquivalent(got_root, expected)
-
-          # Same XML, but with different namespace prefixes
-          got = b"""<?xml version="1.0" encoding="UTF-8" ?>
-          <root xmlns:foo="mynamespace">
-              <foo:tag>foo</foo:tag>
-          </root>"""
-          got_root = self.assertXmlDocument(got)
-          expected = b"""<?xml version="1.0" encoding="UTF-8" ?>
-          <root xmlns:bar="mynamespace">
-              <bar:tag>foo</bar:tag>
-          </root>"""
-          self.assertXmlEquivalent(got, expected)
-          self.assertXmlEquivalent(got_root, expected)
-
-          # Check comparison failure
-          got = b"""<?xml version="1.0" encoding="UTF-8" ?>
-          <root xmlns:foo="mynamespace">
-              <foo:tag> difference here </foo:tag>
-          </root>"""
-          got_root = self.assertXmlDocument(got)
-          with self.assertRaises(self.failureException):
-              self.assertXmlEquivalent(got, expected)
-          with self.assertRaises(self.failureException):
-              self.assertXmlEquivalent(got_root, expected)
-
-
 XML schema conformance assertion
 --------------------------------
 
@@ -648,3 +590,78 @@ your own schema objects in these various schema languages.
           """
           root = test_case.assertXmlDocument(data)
           self.assertXmlValidRelaxNG(root, filename=relaxng_filename)
+
+
+XML documents comparison assertion
+----------------------------------
+
+Sometimes, one may want to check a global XML document, because he know exactly
+what is expected, and can rely on a kind of "string compare". Of course, XML
+is not a simple string, and requires more than just an
+``assert data == expected``, because order of elements can vary, order of
+attributes, etc.
+
+In these cases, one can use the powerful - also dangerous - feature of `LXML
+Output Checker`. See also the documentation of the module
+`doctestcompare <http://lxml.de/api/lxml.doctestcompare-module.html>`_ for
+more information on the underlying implementation.
+
+And as always, remember that the whole purpose of this :py:mod:`xmlunittest`
+is to **not** compare XML formated string. But, whatever, this function could
+help. May be.
+
+.. py:method:: XmlTestMixin.assertXmlEquivalentOutputs(data, expected)
+
+   :param string data: XML formated string to check
+   :param string expected: XML formated string used as reference
+
+   Asserts both XML formated string are equivalent. The comparison ignores
+   spaces within nodes and namespaces may be associated to diffrerent prefixes,
+   thus requiring only the same URL.
+
+   If a difference is found, an :py:exc:`AssertionError` is raised, with the
+   comparison failure's message as error's message.
+
+   .. note::
+
+      The name ``assertXmlEquivalentOutputs`` is cleary a way to prevent user
+      to missunderstand the meaning of this assertion: it checks only similar
+      **outputs**, not **document**.
+
+   .. note::
+
+      This method only accept ``string`` as arguments. This is an opinionated
+      implementation choice, as the purpose of this method is to check
+      the result outputs of an XML document.
+
+
+   .. rubric:: Example
+
+   ::
+
+      # ...
+
+      def test_custom_test(self):
+          """Same XML (with different spacings placements and attrs order)"""
+          # This XML string should come from the code one want to test
+          data = b"""<?xml version="1.0" encoding="UTF-8" ?>
+          <root><tag bar="foo" foo="bar"> foo </tag></root>"""
+
+          # This is the former XML document one can expect, with pretty print
+          expected = b"""<?xml version="1.0" encoding="UTF-8" ?>
+          <root>
+              <tag foo="bar" bar="foo">foo</tag>
+          </root>"""
+
+          # This will pass
+          test_case.assertXmlEquivalentOutputs(data, expected)
+
+          # This is another example of result, with a missing attribute
+          data = b"""<?xml version="1.0" encoding="UTF-8" ?>
+          <root>
+              <tag foo="bar"> foo </tag>
+          </root>
+          """
+
+          # This won't pass
+          test_case.assertXmlEquivalentOutputs(data, expected)

setup.py

@@ -27,7 +27,7 @@
 ]
 
 setup(name='xmlunittest',
-      version='0.1.1',
+      version='0.2.0',
       description='Library using lxml and unittest for unit testing XML.',
       long_description=long_description,
       author='Florian Strzelecki',

test.py

@@ -813,46 +813,74 @@ def test_assertXmlValidRelaxNG_no_relaxng(self):
 
     # -------------------------------------------------------------------------
 
-    def test_assertXmlEquivalent(self):
-        """Asserts assertXmlEquivalent raises when comparison failed.
+    def test_assertXmlEquivalentOutputs(self):
+        """Asserts assertXmlEquivalentOutputs raises when comparison failed.
+
+        Basic assertion: same document, with different order of attributes,
+        text with useless spaces, etc.
+
         """
-        test_case = XmlTestCase(methodName='assertXmlEquivalent')
+        test_case = XmlTestCase(methodName='assertXmlEquivalentOutputs')
 
         # Same XML (with different spacings placements and attrs order)
-        got = b"""<?xml version="1.0" encoding="UTF-8" ?>
+        data = b"""<?xml version="1.0" encoding="UTF-8" ?>
         <root>
             <tag foo="bar" bar="foo">foo</tag>
         </root>"""
-        got_root = test_case.assertXmlDocument(got)
         expected = b"""<?xml version="1.0" encoding="UTF-8" ?>
         <root><tag bar="foo" foo="bar"> foo </tag></root>"""
 
-        test_case.assertXmlEquivalent(got, expected)
-        test_case.assertXmlEquivalent(got_root, expected)
+        test_case.assertXmlEquivalentOutputs(data, expected)
+
+        # Not the right element given
+        wrong_element = b"""<?xml version="1.0" encoding="UTF-8" ?>
+        <root>
+            <notTag foo="bar" bar="foo">foo</notTag>
+        </root>"""
+
+        with self.assertRaises(test_case.failureException):
+            test_case.assertXmlEquivalentOutputs(wrong_element, expected)
+
+        # Too many tag elements
+        data = b"""<?xml version="1.0" encoding="UTF-8" ?>
+        <root>
+            <tag foo="bar" bar="foo">foo</tag>
+            <tag foo="bar" bar="foo">foo</tag>
+        </root>"""
+
+        with self.assertRaises(test_case.failureException):
+            test_case.assertXmlEquivalentOutputs(wrong_element, expected)
+
+    def test_assertXmlEquivalentOutputs_namespaces(self):
+        """Asserts assertXmlEquivalentOutputs raises when comparison failed.
+
+        Assertion with different namespaces: the namespace URI is the same,
+        but the prefix is different. In this case, the two XML are equivalents.
+
+        """
+        test_case = XmlTestCase(methodName='assertXmlEquivalentOutputs')
 
         # Same XML, but with different namespace prefixes
-        got = b"""<?xml version="1.0" encoding="UTF-8" ?>
+        data = b"""<?xml version="1.0" encoding="UTF-8" ?>
         <root xmlns:foo="mynamespace">
             <foo:tag>foo</foo:tag>
         </root>"""
-        got_root = test_case.assertXmlDocument(got)
+
         expected = b"""<?xml version="1.0" encoding="UTF-8" ?>
         <root xmlns:bar="mynamespace">
             <bar:tag>foo</bar:tag>
         </root>"""
-        test_case.assertXmlEquivalent(got, expected)
-        test_case.assertXmlEquivalent(got_root, expected)
 
-        # Check comparison failure
-        got = b"""<?xml version="1.0" encoding="UTF-8" ?>
-        <root xmlns:foo="mynamespace">
-            <foo:tag> difference here </foo:tag>
-        </root>"""
-        got_root = test_case.assertXmlDocument(got)
-        with self.assertRaises(test_case.failureException):
-            test_case.assertXmlEquivalent(got, expected)
+        test_case.assertXmlEquivalentOutputs(data, expected)
+
+        wrong_namespace = b"""<?xml version="1.0" encoding="UTF-8" ?>
+        <root xmlns:foo="not_the_same_namespace">
+            <foo:tag>foo</foo:tag>
+        </root>
+        """
+
         with self.assertRaises(test_case.failureException):
-            test_case.assertXmlEquivalent(got_root, expected)
+            test_case.assertXmlEquivalentOutputs(wrong_namespace, expected)
 
 
 if __name__ == "__main__":

xmlunittest.py

@@ -10,6 +10,9 @@
 from lxml.doctestcompare import LXMLOutputChecker, PARSE_XML
 
 
+__all__ = ['XmlTestMixin', 'XmlTestCase']
+
+
 class XmlTestMixin(object):
     """Base mixin class for XML unittest.
 
@@ -156,19 +159,6 @@ def assertXpathValues(self, node, xpath, values):
                           % (node.tag, xpath, result,
                              etree.tostring(node, pretty_print=True)))
 
-    def assertXmlEquivalent(self, got, expect):
-        """Asserts both xml parse to the same results
-        `got` may be an XML string or lxml Element
-        """
-        checker = LXMLOutputChecker()
-
-        if isinstance(got, etree._Element):
-            got = etree.tostring(got)
-
-        if not checker.check_output(expect, got, PARSE_XML):
-            message = checker.output_difference(doctest.Example("", expect), got, PARSE_XML)
-            self.fail(message)
-
     def assertXmlValidDTD(self, node, dtd=None, filename=None):
         """Asserts XML node is valid according to the given DTD."""
         schema = None
@@ -226,6 +216,24 @@ def assertXmlValidRelaxNG(self, node, relaxng=None, filename=None):
         if not schema.validate(node):
             self.fail(schema.error_log.last_error)
 
+    def assertXmlEquivalentOutputs(self, data, expected):
+        """Asserts both XML outputs are equivalent.
+
+        This assertion use the powerful but dangerous feature of
+        LXMLOutputChecker. Powerful because one can compare two XML document
+        in their meaning, but dangerous because sometimes there is more to
+        check than just a kind of output.
+
+        See LXMLOutputChecker documentation for more information.
+
+        """
+        checker = LXMLOutputChecker()
+
+        if not checker.check_output(expected, data, PARSE_XML):
+            message = checker.output_difference(doctest.Example("", expected),
+                                                data, PARSE_XML)
+            self.fail(message)
+
 
 class XmlTestCase(unittest.TestCase, XmlTestMixin):
     """XML test case for unit test using python unittest built-in package.