With the DiffBuilder you can build the difference between two XML Sources in human readable fluent style.

By default the Diff returned by DiffBuilder contains DIFFERENT and SIMILAR Differences. If you want to ignore SIMILAR Differences use checkForSimilar.

This example will throw an AssertionError: "Expected attribute value 'abc' but was 'xyz'".

final String control = "<a><b attr=\"abc\"></b></a>";
final String test = "<a><b attr=\"xyz\"></b></a>";

Diff myDiff = DiffBuilder.compare(Input.fromString(control))
              .withTest(Input.fromString(test))
              .build();
              
Assert.assertFalse(myDiff.toString(), myDiff.hasDifferences());

the C# equivalent would be

string control = "<a><b attr=\"abc\"></b></a>";
string test = "<a><b attr=\"xyz\"></b></a>";

var myDiff = DiffBuilder.Compare(Input.FromString(control))
              .WithTest(Input.FromString(test))
              .Build();
              
Assert.IsFalse(myDiff.HasDifferences(), myDiff.ToString());

The name Diff is a class and a namespace name in XMLUnit.NET which may force you to alias the class name in using statements. In the examples we'll always use var to avoid the ambiguity.

You can compare all kind of Objects with each other which can be used as a XML source.

See: Providing Input To XMLUnit - Input.from(Object)

The DiffBuilder can be configured via fluent API:

Diff myDiff = DiffBuilder.compare(control)
        .withTest(test)
        .checkForSimilar().checkForIdentical() // [1]
        .ignoreComments() // [2]
        .ignoreWhitespace() // [3]
        .normalizeWhitespace() // [4]
        .withComparisonController(ComparisonController) // [5]
        .withComparisonFormatter(comparisonFormatter) // [6]
        .withComparisonListeners(comparisonListeners) // [7]
        .withDifferenceEvaluator(differenceEvaluator) // [8]
        .withDifferenceListeners(comparisonListeners) // [9]
        .withNodeMatcher(nodeMatcher) // [10]
        .withAttributeFilter(attributeFilter) // [11]
        .withNodeFilter(nodeFilter) // [12]
        .withNamespaceContext(map) // [13]
        .withDocumentBuilerFactory(factory) // [14]
        .ignoreElementContentWhitespace() // [15]

1. checkForSimilar() checkForIdentical():
   The default is checkForIdentical and leads to a Diff that contains DIFFERENT and SIMILAR Differences. When checkForSimilar is used, SIMILAR Differences are ignored. The Difference between identical and similar is decided by the default DifferenceEvaluator.
2. ignoreComments():
   will stripping all comments from the test- and control-XML before comparing.
3. ignoreWhitespace():
   will removing all empty text nodes and trimming the non-empty ones from the test- and control-XML before comparing.
4. normalizeWhitespace():
   will removing all empty text nodes and normalizing the non-empty ones from the test- and control-XML before comparing. With "normalized" in this context means all whitespace characters are replaced by space characters and consecutive whitespace characters are collapsed.
5. withComparisonController():
   The default ComparisonController will let the DifferenceEngine evaluate all differences between test and control XML.
   If the evaluation should stop after the first found difference you must use the ComparisonControllers.StopWhenDifferent instead.
   See withComparisonController()
6. withComparisonFormatter():
   Use a custom Formatter for the Error Messages.
   See ComparisonFormatter.
7. withComparisonListeners():
   Registers a listener that is notified of each comparison.
   See ComparisonListener.
8. withDifferenceEvaluator():
   Provide your own custom DifferenceEvaluator implementation.
   See DifferenceEvaluator.
9. withDifferenceListeners():
   Registers a listener that is notified of each comparison with outcome other than ComparisonResult.EQUAL.
   See ComparisonListener.
10. withNodeMatcher():
    Sets the strategy for selecting nodes to compare.
    See NodeMatcher.
11. withAttributeFilter(): Optional strategy that allows certain attributes to be ignore completely. See AttributeFilter.
12. withNodeFilter(): Optional strategy that allows certain nodes to be ignore completely. See NodeFilter.
13. withNamespaceContext():
    Establish a namespace context that will be used in Comparison.Detail.getXPath().
    Without a namespace context (or with an empty context) the XPath expressions will only use local names for elements and attributes.
    See NamespaceContext
14. withDocumentBuilderFactory(): Use the given DocumentBuilderFactory when creating a document from the test or control source. Only available in XMLUnit for Java - since XMLUnit 2.2.0.
15. ignoreElementContentWhitespace(): will removing all text nodes solely consisting of whitespace (AKA as element content whitespace) - since XMLUnit 2.6.0.

the .NET version is almost the same, only the method names are capitalized.

Assuming you compare two XMLs with two differences (attr1 and attr2):

final String control = "<a><b attr1=\"abc\" attr2=\"def\"></b></a>";
final String test = "<a><b attr1=\"uvw\" attr2=\"xyz\"></b></a>";

The default ComparisonController will let evaluate all differences:

Diff myDiff = DiffBuilder.compare(control).withTest(test)
        .build();

assertThat(Linqy.count(myDiff.getDifferences()), is(2));

With the custom ComparisonController ComparisonControllers.StopWhenDifferent comparison is cut short once the first difference has been encountered and only the first difference will be returned:

Diff myDiff = DiffBuilder.compare(control).withTest(test)
        .withComparisonController(ComparisonControllers.StopWhenDifferent)
        .build();

assertThat(Linqy.count(myDiff.getDifferences()), is(1));

Use this if you need special configuration of the DocumentBuilderFactory. A bug in XMLUnit 2.2.0 ignores this setting when you use ignoreWhitespace or normalizeWhitespace at the same time, this has been fixed in 2.2.1. ignoreComments uses XSLT under the covers and may reduce the effect of setting the DocumentBuilderFactory as the TransformerFactory may need to be configured as well.