DiffBuilder

DiffBuilder

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

Basic Example

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.assertTrue(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.IsTrue(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.

Test-Objects and Control-Objects

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)

fluent API

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(); // [13]

1. checkForSimilar() checkForIdentical():
   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 withNamespaceContext()

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

withComparisonController()

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));

withNamespaceContext()

TODO Examples?