DifferenceEvaluator

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

A DifferenceEvaluator can evaluate the significance of differences.

Default DifferenceEvaluator

The DifferenceEvaluators.Default makes the decision if a difference is similar.
With the default evaluator, the following differences are handled as similar:

• CDATA and Text nodes with the same content
• DOCTYPE differences
• different xsi:noNamspaceSchemaLocation and xsi:noNamspaceSchemaLocation
• different Namespaces Prefixes
• explicit/implicit status of attributes.
• a different order of child nodes
• XML encoding

If you use your own DifferenceEvaluator implementation you can combine it with the default DifferenceEvaluator.

Example implementations

❗ This Example implementations are strongly simplified without exception handling or not-null checks. They should only be a clue what a DifferenceEvaluator can do. ❗

Ignoring a special attribute

In some cases you want ignore some special differences of an XML content. Typical cases are elements/attributes which are filled with random values like UUIDs or current date/time informations.

private final class IgnoreAttributeDifferenceEvaluator implements DifferenceEvaluator {

    private String attributeName;

    public IgnoreAttributeDifferenceEvaluator(String attributeName) {
        this.attributeName = attributeName;
    }

    @Override
    public ComparisonResult evaluate(Comparison comparison, ComparisonResult outcome) {
        if (outcome == ComparisonResult.EQUAL) return outcome; // only evaluate differences.
        final Node controlNode = comparison.getControlDetails().getTarget();
        if (controlNode instanceof Attr) {
            Attr attr = (Attr) controlNode;
            if (attr.getName().equals(attributeName)) {
                return ComparisonResult.SIMILAR; // will evaluate this difference as similar
            }
        }
        return outcome;
    }
} 

Usage:

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

Diff myDiff = DiffBuilder.compare(control).withTest(test)
        .withDifferenceEvaluator(new IgnoreAttributeDifferenceEvaluator("attr"))
        .checkForSimilar()
        .build();

Assert.assertFalse(myDiff.toString(), myDiff.hasDifferences());

Compare an element manually

In some cases you don't want compare the content of an element as String. This example shows how to compare a special element with BigDecimal.
Because for our fictive business case it doesn't mater if the value is "1.0" or "1.00".

private final class BigDecimalElementDifferenceEvaluator implements DifferenceEvaluator {

    private String elementName;

    public BigDecimalElementDifferenceEvaluator(String elementName) {
        this.elementName = elementName;
    }

    @Override
    public ComparisonResult evaluate(Comparison comparison, ComparisonResult outcome) {
        if (outcome == ComparisonResult.EQUAL) return outcome; // only evaluate differences.
        final Node controlNode = comparison.getControlDetails().getTarget();
        final Node testNode = comparison.getTestDetails().getTarget();
        if (controlNode.getParentNode() instanceof Element && testNode.getParentNode() instanceof Element) {
            Element controlElement = (Element) controlNode.getParentNode();
            Element testElement = (Element) testNode.getParentNode();
            if (controlElement.getNodeName().equals(elementName)) {
                final String controlValue = controlElement.getTextContent();
                final String testValue = testElement.getTextContent();
                if (new BigDecimal(controlValue).compareTo(new BigDecimal(testValue)) == 0) {
                    return ComparisonResult.SIMILAR;
                }
            }
        }
        return outcome;
    }
}

Usage:

final String control = "<a><amount>1</amount></a>";
final String test = "<a><amount>1.0000</amount></a>";

Diff myDiff = DiffBuilder.compare(control).withTest(test)
        .withDifferenceEvaluator(new BigDecimalElementDifferenceEvaluator("amount"))
        .checkForSimilar()
        .build();

Assert.assertFalse(myDiff.toString(), myDiff.hasDifferences());

combine DifferenceEvaluators

If you want use your own DifferenceEvaluator implementation in combination with the default DifferenceEvaluator you must combine them:

Diff myDiff = DiffBuilder.compare(control).withTest(test)
        .withDifferenceEvaluator(
            DifferenceEvaluators.chain(DifferenceEvaluators.Default,
            new MyCustomDifferenceEvaluator()))
        .checkForSimilar()
        .build();

There are two helper methods to combine DifferenceEvaluators:

• DifferenceEvaluators.first(...)
  Combines multiple DifferenceEvaluators so that the first one that changes the outcome wins.
• DifferenceEvaluators.chain(...)
  Combines multiple DifferenceEvaluators so that the result of the first Evaluator will be passed to the next Evaluator.