CompareMatcher

	XMLUnit 2.x has not been released, yet. This documentation may change until the final release of XMLUnit.

The Hamcrest CompareMatcher compares two XML sources with each others.

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

assertThat(test, CompareMatcher.isIdenticalTo(control));

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)

similar vs identical

The Difference between identical and similar is decided by the default DifferenceEvaluator.

fluent API

The compare Matcher can be configured via fluent API:

CompareMatcher.isSimilarTo(control)
    .ignoreComments() // [1]
    .ignoreWhitespace() // [2]
    .normalizeWhitespace() // [3]
    .throwComparisonFailure() // [4]
    .withComparisonFormatter(comparisonFormatter) // [5]
    .withComparisonListeners(comparisonListeners) // [6]
    .withDifferenceEvaluator(differenceEvaluator) // [7]
    .withDifferenceListeners(comparisonListeners) // [8]
    .withNodeMatcher(nodeMatcher); // [9]

1. ignoreComments():
   will stripping all comments from the test- and control-XML before comparing.
2. ignoreWhitespace():
   will removing all empty text nodes and trimming the non-empty ones from the test- and control-XML before comparing.
3. 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.
4. throwComparisonFailure():
   This will throw a org.junit.ComparisonFailure in case of differences. Eclipse, IntelliJ and NetBeans can than show you a nice Diff-View of the differences.
   See throwComparisonFailure.
5. withComparisonFormatter():
   Use a custom Formatter for the Error Messages.
   See ComparisonFormatter.
6. withComparisonListeners():
   Registers a listener that is notified of each comparison.
   See ComparisonListener.
7. withDifferenceEvaluator():
   Provide your own custom DifferenceEvaluator implementation.
   See DifferenceEvaluator.
8. withDifferenceListeners():
   Registers a listener that is notified of each comparison with outcome other than ComparisonResult.EQUAL.
   See ComparisonListener.
9. withNodeMatcher():
   Sets the strategy for selecting nodes to compare.
   See NodeMatcher.

throwComparisonFailure()

Instead of Matcher returning false a org.junit.ComparisonFailure will be thrown.

The advantage over the standard Matcher behavior is, that the ComparisonFailure can provide the effected Control-Node and Test-Node in separate Properties. Eclipse, NetBeans and IntelliJ can provide a nice DIFF-View for the two values. ComparisonFailure is also used in org.junit.Assert.assertEquals(Object, Object) if both values are Strings:

The only disadvantage is, that you can't combine the CompareMatcher with other Matchers (like org.hamcrest.CoreMatchers.not(Object)) anymore. The following code will NOT WORK properly: assertThat(test, not(isSimilarTo(control).throwComparisonFailure()))