A. Changes

A.1. Changes from XMLUnit 1.0 to 1.1

XMLUnit 1.1's main focus was to add two features that have been asked for repeatedly:

  • Support for XML Namespaces in XPath processing
  • Support for XML Schema validation.

In addition some JAXP features that have been added after the release of XMLUnit 1.0 are now supported - most notably XPath support - and all reported bugs and feature requests have been addressed.

A.1.1. Breaking Changes

  • XMLTestCase is now abstract. You probably have never created instances of this class without subclassing it, but if you did, your code will now break. You will most likely want to look at the XMLAssert class.
  • All methods that have been deprecated in XMLUnit 1.0 have been removed.

  • All methods that had been declared to throw TransformerConfigurationException or ParserConfigurationException now no longer declare it. Exceptions of these types cannot be recovered from anyway, so XMLUnit will now wrap them in a org.custommonkey.xmlunit.exceptions.ConfigurationException which is an unchecked exception.

    This change doesn't have a big impact on your tests, but if you tried to catch these exceptions they will now bypass your catch blocks.

  • A new type of Difference (CHILD_NODE_NOT_FOUND_ID) has been added. It will be raised for the excess children if the control element has more child nodes than the test element - or vice versa.

    Prior to XMLUnit 1.1 a Difference of either ELEMENT_TAG_NAME_ID or NODE_TYPE_ID would have been raised if the control element had more children. The excess children were compared to the very first child node of the test element. Excess children of the test element were not reported at all.

  • The schemaLocation and noNamespaceSchemaLocation attributes of the XMLSchema-Instance Namespace are now treated in a different way from "normal" attributes. They will be flagged as new kinds of Difference that is recoverable.

    This means that two pieces of XML that were different in XMLUnit 1.0 because they differed in one of the two attributes will be similar in XMLUnit 1.1.

  • When comparing two elements that differ on attributes the comparison is now symmetric.

    In XMLUnit 1.0 if an attribute was present on the test but not the control element this wasn't flagged as a Difference; in XMLUnit 1.1 it is.

    In most practical cases this doesn't cause any problems since the two elements either have a different number of attributes or there are attributes in the control element that are missing in the test element - so the pieces of XML have been flagged as different before as well. If you are using DetailedDiff this change may lead to more detected Differences, though.

A.1.2. New Features

  • XMLUnit 1.0 shipped with rudimentary support for XML Schema validation (it worked with Apache Xerces-J but no other parsers). XMLUnit 1.1 supports Schema validation for any JAXP compliant XML parser (that supports Schema itself). You can also tell XMLUnit where to look for the XML Schema definitions. See Section 4.1.2, “XML Schema Validation” for details.
  • XPath support has undergone significant changes, see Section 5, “XPath Tests” for more details. In particular XMLUnit will now use javax.xml.xpath if it is available (which also helps to avoid the buggy XSLTC version that is the default transformer engine in Java 5) and supports XML namespaces.
  • Several new configuration options have been added, see Section 3.8, “Configuration Options”.
  • It is now possible to provide a custom org.xml.sax.EntityResolver for control and test parsers.
  • It is now possible to provide a custom javax.xml.transform.URIResolver for transformations.
  • New overloads have been added that allow org.xml.sax.InputSource to be used as a "piece of XML" in many classes.
  • Validator will now use the custom EntityResolverconfigured for the "control" parser as a fallback.
  • A new package org.custommonkey.xmlunit.examples has been added that showcases some of XMLUnit's abilities. It currently contains two classes:

    1. MultiLevelElementNameAndTextQualifier see Section 3.4.5, “org.custommonkey.xmlunit.examples.MultiLevelElementNameAndTextQualifier for a description.
    2. XPathRegexAssert that provides a JUnit 3.x like assertXPathMatches method to verify that the string-ified value of an XPath match matches a given regular expression (requires JDK 1.4 or above).

A.1.3. Important Bug Fixes

  • ElementNameAndAttributeQualifier would throw an NullPointerException if the control piece of XML contained attributes that were missing in the test piece of XML. Issue 952920.
  • XMLTestCase.assertXMLNotEqual(String, Reader, Reader) delegated to assertXMLEqual instead of assertXMLNotEqual internally, negating the assertion's logic. Issue 956372.
  • XMLTestCase.assertXMLIdentical(Diff, boolean) delegated to assertXMLEqual, weakening the assertion.
  • Under certain circumstances the reported XPath expressions for nodes that showed differences were wrong. XMLUnit could lose the root element or erroneously append an extra attribute name. Issues 1047364 and 1027863.
  • TolerantSaxParser's logic in characters was broken and could cause StringIndexOutOfBoundsExceptions. Issue 1150234.