At the center of XMLUnit's support for comparisons is the DifferenceEngine class. In practice you rarely deal with it directly but rather use it via instances of Diff or DetailedDiff classes (see Section 3.5, “Diff and DetailedDiff”).

The DifferenceEngine walks two trees of DOM Nodes, the control and the test tree, and compares the nodes. Whenever it detects a difference, it sends a message to a configured DifferenceListener (see Section 3.3, “DifferenceListener”) and asks a ComparisonController (see Section 3.2, “ComparisonController”) whether the current comparison should be halted.

In some cases the order of elements in two pieces of XML may not be significant. If this is true, the DifferenceEngine needs help to determine which Elements to compare. This is the job of an ElementQualifier (see Section 3.4, “ElementQualifier”).

The types of differences DifferenceEngine can detect are enumerated in the DifferenceConstants interface and represented by instances of the Difference class.

A Difference can be recoverable; recoverable Differences make the Diff class consider two pieces of XML similar while non-recoverable Differences render the two pieces different.

The types of Differences that are currently detected are listed in Table 1, “Document level Differences detected by DifferenceEngine” to Table 4, “Other Differences detected by DifferenceEngine” (the first two columns refer to the DifferenceConstants class).

Note that some of the differences listed may be ignored by the DifferenceEngine if certain configuration options have been specified. See Section 3.8, “Configuration Options” for details.

DifferenceEngine passes differences found around as instances of the Difference class. In addition to the type of of difference this class also holds information on the nodes that have been found to be different. The nodes are described by NodeDetail instances that encapsulate the DOM Node instance as well as the XPath expression that locates the Node inside the given piece of XML. NodeDetail also contains a "value" that provides more information on the actual values that have been found to be different, the concrete interpretation depends on the type of difference as can be seen in Table 5, “Contents of NodeDetail.getValue() for Differences”.

As said in the first paragraph you won't deal with DifferenceEngine directly in most cases. In cases where Diff or DetailedDiff don't provide what you need you'd create an instance of DifferenceEngine passing a ComparisonController in the constructor and invoke compare with your DOM trees to compare as well as a DifferenceListener and ElementQualifier. The listener will be called on any differences while the control method is executing.

class MyDifferenceListener implements DifferenceListener {
    private boolean calledFlag = false;
    public boolean called() { return calledFlag; }

    public int differenceFound(Difference difference) {
        calledFlag = true;
        return RETURN_ACCEPT_DIFFERENCE;
    }

    public void skippedComparison(Node control, Node test) {
    }
}

DifferenceEngine engine = new DifferenceEngine(myComparisonController);
MyDifferenceListener listener = new MyDifferenceListener();
engine.compare(controlNode, testNode, listener,
               myElementQualifier);
System.err.println("There have been "
                   + (listener.called() ? "" : "no ")
                   + "differences.");

The ComparisonController's job is to decide whether a comparison should be halted after a difference has been found. Its interface is:

    /**
     * Determine whether a Difference that the listener has been notified of
     *  should halt further XML comparison. Default behaviour for a Diff
     *  instance is to halt if the Difference is not recoverable.
     * @see Difference#isRecoverable
     * @param afterDifference the last Difference passed to <code>differenceFound</code>
     * @return true to halt further comparison, false otherwise
     */
    boolean haltComparison(Difference afterDifference);

Whenever a difference has been detected by the DifferenceEngine the haltComparison method will be called immediately after the DifferenceListener has been informed of the difference. This is true no matter what type of Difference has been found or which value the DifferenceListener has returned.

The only implementations of ComparisonController that ship with XMLUnit are Diff and DetailedDiff, see Section 3.5, “Diff and DetailedDiff” for details about them.

A ComparisonController that halted the comparison on any non-recoverable difference could be implemented as:

public class HaltOnNonRecoverable implements ComparisonController {
    public boolean haltComparison(Difference afterDifference) {
        return !afterDifference.isRecoverable();
    }
}

DifferenceListener contains two callback methods that are invoked by the DifferenceEngine when differences are detected:

    /**
     * Receive notification that 2 nodes are different.
     * @param difference a Difference instance as defined in {@link
     * DifferenceConstants DifferenceConstants} describing the cause
     * of the difference and containing the detail of the nodes that
     * differ
     * @return int one of the RETURN_... constants describing how this
     * difference was interpreted
     */
    int differenceFound(Difference difference);

    /**
     * Receive notification that a comparison between 2 nodes has been skipped
     *  because the node types are not comparable by the DifferenceEngine
     * @param control the control node being compared
     * @param test the test node being compared
     * @see DifferenceEngine
     */
    void skippedComparison(Node control, Node test);

differenceFound is invoked by DifferenceEngine as soon as a difference has been detected. The return value of that method is completely ignored by DifferenceEngine, it becomes important when used together with Diff, though (see Section 3.5, “Diff and DetailedDiff”). The return value should be one of the four constants defined in the the DifferenceListener interface:

    /** 
     * Standard return value for the <code>differenceFound</code> method.
     * Indicates that the <code>Difference</code> is interpreted as defined 
     * in {@link DifferenceConstants DifferenceConstants}.
     */
    int RETURN_ACCEPT_DIFFERENCE;
    /** 
     * Override return value for the <code>differenceFound</code> method.
     * Indicates that the nodes identified as being different should be 
     * interpreted as being identical.
     */
    int RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL;
    /** 
     * Override return value for the <code>differenceFound</code> method.
     * Indicates that the nodes identified as being different should be 
     * interpreted as being similar.
     */
    int RETURN_IGNORE_DIFFERENCE_NODES_SIMILAR;
    /** 
     * Override return value for the <code>differenceFound</code> method.
     * Indicates that the nodes identified as being similar should be 
     * interpreted as being different.
     */
    int RETURN_UPGRADE_DIFFERENCE_NODES_DIFFERENT = 3;

The skippedComparison method is invoked if the DifferenceEngine encounters two Nodes it cannot compare. Before invoking skippedComparison DifferenceEngine will have invoked differenceFound with a Difference of type NODE_TYPE.

A custom DifferenceListener that ignored any DOCTYPE related differences could be written as:

public class IgnoreDoctype implements DifferenceListener {
    private static final int[] IGNORE = new int[] {
        DifferenceConstants.HAS_DOCTYPE_DECLARATION_ID,
        DifferenceConstants.DOCTYPE_NAME_ID,
        DifferenceConstants.DOCTYPE_PUBLIC_ID_ID,
        DifferenceConstants.DOCTYPE_SYSTEM_ID_ID
    };

    static {
        Arrays.sort(IGNORE);
    }

    public int differenceFound(Difference difference) {
        return Arrays.binarySearch(IGNORE, difference.getId()) >= 0
            ? RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL
            : RETURN_ACCEPT_DIFFERENCE;
    }
    
    public void skippedComparison(Node control, Node test) {
    }
}

Apart from Diff and DetailedDiff XMLUnit ships with an additional implementation of DifferenceListener.

When DifferenceEngine encounters a list of DOM Elements as children of another Element it will ask the configured ElementQualifier which Element of the control piece of XML should be compared to which of the test piece. Its contract is:

    /**
     * Determine whether two elements are comparable
     * @param control an Element from the control XML NodeList
     * @param test an Element from the test XML NodeList
     * @return true if the elements are comparable, false otherwise
     */
    boolean qualifyForComparison(Element control, Element test); 

For any given Element in the control piece of XML DifferenceEngine will cycle through the corresponding list of Elements in the test piece of XML until qualifyForComparison has returned true or the test document is exhausted.

When using DifferenceEngine or Diff it is completely legal to set the ElementQualifier to null. In this case any kind of Node is compared to the test Node that appears at the same position in the sequence.

<!-- control piece of XML -->
<parent>
  <child1/>                        <!-- control node 1 -->
  <child2/>                        <!-- control node 2 -->
  <child2 foo="bar">xyzzy</child2> <!-- control node 3 -->
  <child2 foo="baz"/>              <!-- control node 4 -->
</parent>

<!-- test piece of XML -->
<parent>
  <child2 foo="baz"/>              <!-- test node 1 -->
  <child1/>                        <!-- test node 2 -->
  <child2>xyzzy</child2>           <!-- test node 3 -->
  <child2 foo="bar"/>              <!-- test node 4 -->
</parent>

Taking Example 19, “Example Nodes for ElementQualifier (the comments are not part of the example)” without any ElementQualifier DifferenceEngine will compare control node n to test node n for n between 1 and 4. In many cases this is exactly what is desired, but sometimes <a><b/><c/></a> should be similar to <a><c/><b/></a> because the order of elements doesn't matter - this is when you'd use a different ElementQualifier. XMLUnit ships with several implementations.

<!-- control -->
<table>
  <tr>            <!-- control row 1 -->
    <td>foo</td>
  </tr>
  <tr>            <!-- control row 2 -->
    <td>bar</td>
  </tr>
</table>

<!-- test -->
<table>
  <tr>            <!-- test row 1 -->
    <td>bar</td>
  </tr>
  <tr>            <!-- test row 2 -->
    <td>foo</td>
  </tr>
</table>

Diff and DetailedDiff provide simplified access to DifferenceEngine by implementing the ComparisonController and DifferenceListener interfaces themselves. They cover the two most common use cases for comparing two pieces of XML: checking whether the pieces are different (this is what Diff does) and finding all differences between them (this is what DetailedDiff does).

DetailedDiff is a subclass of Diff and can only be constructed by creating a Diff instance first.

The major difference between them is their implementation of the ComparisonController interface: DetailedDiff will never stop the comparison since it wants to collect all differences. Diff in turn will halt the comparison as soon as the first Difference is found that is not recoverable. In addition DetailedDiff collects all Differences in a list and provides access to it.

By default Diff will consider two pieces of XML as identical if no differences have been found at all, similar if all differences that have been found have been recoverable (see Table 1, “Document level Differences detected by DifferenceEngine” to Table 4, “Other Differences detected by DifferenceEngine”) and different as soon as any non-recoverable difference has been found.

It is possible to specify a DifferenceListener to Diff using the overrideDifferenceListener method. In this case each Difference will be evaluated by the passed in DifferenceListener. By returning RETURN_IGNORE_DIFFERENCE_NODES_IDENTICAL the custom listener can make Diff ignore the difference completely. Likewise any Difference for which the custom listener returns RETURN_IGNORE_DIFFERENCE_NODES_SIMILAR will be treated as if the Difference was recoverable.

There are several overloads of the Diff constructor that allow you to specify your piece of XML in many ways. There are overloads that accept additional DifferenceEngine and ElementQualifier arguments. Passing in a DifferenceEngine of your own is the only way to use a ComparisonController other than Diff.

Note that Diff and DetailedDiff use ElementNameQualifier as their default ElementQualifier. This is different from DifferenceEngine which defaults to no ElementQualifier at all.

To use a custom ElementQualifier you can also use the overrideElementQualifier method. Use this with an argument of null to unset the default ElementQualifier as well.

To compare two pieces of XML you'd create a Diff instance from those two pieces and invoke identical to check that there have been no differences at all and similar to check that any difference, if any, has been recoverable. If the pieces are identical they are also similar. Likewise if they are not similar they can't be identical either.

Diff d = new Diff("<a><b/><c/></a>", "<a><c/><b/></a>");
assertFalse(d.identical()); // CHILD_NODELIST_SEQUENCE Difference
assertTrue(d.similar());

The result of the comparison is cached in Diff, repeated invocations of identical or similar will not reevaluate the pieces of XML.

Note: calling toString on an instance of Diff or DetailedDiff will perform the comparision and cache its result immediately. If you change the DifferenceListener or ElementQualifier after calling toString it won't have any effect.

DetailedDiff provides only a single constructor that expects a Diff as argument. Don't use DetailedDiff if all you need to know is whether two pieces of XML are identical/similar - use Diff directly since its short-cut ComparisonController implementation will save time in this case.

Diff d = new Diff("<a><b/><c/></a>", "<a><c/><b/></a>");
DetailedDiff dd = new DetailedDiff(d);
dd.overrideElementQualifier(null);
assertFalse(dd.similar());
List l = dd.getAllDifferences();
assertEquals(2, l.size()); // expected <b/> but was <c/> and vice versa

Sometimes you might be interested in any sort of comparison result and want to get notified of successful matches as well. Maybe you want to provide feedback on the amount of differences and similarities between two documents, for example.

The interface MatchTracker can be implemented to get notified on each and every successful match, note that there may be a lot more comparisons going on than you might expect and that your callback gets notified a lot.

package org.custommonkey.xmlunit;

/**
 * Listener for callbacks from a {@link DifferenceEngine#compare
 * DifferenceEngine comparison} that is notified on each and every
 * comparision that resulted in a match.
 */
public interface MatchTracker {
    /**
     * Receive notification that 2 match.
     * @param match a Difference instance as defined in {@link
     * DifferenceConstants DifferenceConstants} describing the test
     * that matched and containing the detail of the nodes that have
     * been compared
     */
    void matchFound(Difference difference);
}

Despite its name the Difference instance passed into the matchFound method really describes a match and not a difference. You can expect that the getValue method on both the control and the test NodeDetail will be equal.

DifferenceEngine provides a constructor overload that allows you to pass in a MatchTracker instance and also provides a setMatchTracker method. Diff and DetailedDiff provide overrideMatchTracker methods that fill the same purpose.

Note that your MatchTracker won't receive any callbacks once the configured ComparisonController has decided that DifferenceEngine should halt the comparison.

XMLAssert and XMLTestCase contain quite a few overloads of methods for comparing two pieces of XML.

The method's names use the word Equal to mean the same as similar in the Diff class (or throughout this guide). So assertXMLEqual will assert that only recoverable differences have been encountered where assertXMLNotEqual asserts that some differences have been non-recoverable. assertXMLIdentical asserts that there haven't been any differences at all while assertXMLNotIdentical asserts that there have been differences (recoverable or not).

Most of the overloads of assertXMLEqual just provide different means to specify the pieces of XML as Strings, InputSources, Readers^[7] or Documents. For each method there is a version that takes an additional err argument which is used to create the message if the assertion fails.

If you don't need any control over the ElementQualifier or DifferenceListener used by Diff these methods will save some boilerplate code. If CONTROL and TEST are pieces of XML represented as one of the supported inputs then

Diff d = new Diff(CONTROL, TEST);
assertTrue("expected pieces to be similar, " + d.toString(),
           d.similar());

and

assertXMLEqual("expected pieces to be similar", CONTROL, TEST);

are equivalent.

If you need more control over the Diff instance there is a version of assertXMLEqual (and assertXMLIdentical) that accepts a Diff instance as its argument as well as a boolean indicating whether you expect the Diff to be similar (identical) or not.

XMLTestCase contains a couple of compareXML methods that really are only shortcuts to Diff's constructors.

There is no way to use DifferenceEngine or DetailedDiff directly via the convenience methods.

Unless you are using Document or DOMSource overrides when specifying your pieces of XML, XMLUnit will use the configured XML parsers (see Section 2.4.1, “JAXP”) and EntityResolvers (see Section 2.4.2, “EntityResolver”). There are configuration options to use different settings for the control and test pieces of XML.

In addition some of the other configuration settings may lead to XMLUnit using the configured XSLT transformer (see Section 2.4.1, “JAXP”) under the covers.

<foo>&lt;bar&gt;</foo>

<foo><![CDATA[<bar>]]></foo>

<root>
  <a/>
</root>

<root>
  <b/>
</root>