Migrating from XMLUnit 1.x to 2.x

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

xmlunit-legacy

If you use xmlunit-legacy, then you must properly change nothing. xmlunit-legacy ist the old XMLUnit 1.x API which uses the new XMlUnit 2.x Engine. But xmlunit-legacy is deprecated and will not be extended. New feature will only be available in xmlunit-core or xmlunit-matchers.

XMLUnit 1.x static Configurations:

XMLUnit 2.x has no static configuration anymore.

XMLUnit 1.x	XMLUnit 2.x
XMLUnit.setIgnoreAttributeOrder()	2.x will always ignore the attribute order.
XMLUnit.setIgnoreComments()	use of "new CommentLessSource(...)" or DiffBuilder.ignoreComments()
XMLUnit.setIgnoreDiffBetweenTextAndCDATA()	in 2.x TEXT and CDATA are marked with ComparisonResult.SIMILAR (another behaviour would require a custom DifferenceEvaluator)
XMLUnit.setIgnoreWhitespace()	use of "new WhitespaceStrippedSource(...)" or DiffBuilder.ignoreWhitespace()
XMLUnit.setNormalizeWhitespace	use of "new WhitespaceNormalizedSource(...)" or DiffBuilder.normalizeWhitespace()

Creating a Diff instance:

Old XMLUnit 1.x Code:

public void testXMLLegacyIdentical()throws Exception {
    String myControlXML =
        "<struct><int>3</int><boolean>false</boolean></struct>";
    String myTestXML =
        "<struct><boolean>false</boolean><int>3</int></struct>";
    Diff myDiff = new Diff(myControlXML, myTestXML);
    assertTrue("XML similar " + myDiff.toString(),
               myDiff.similar());
    assertTrue("XML identical " + myDiff.toString(),
               myDiff.identical());
}

New XMLUnit 2.x Code with xmlunit-core:

public void testXMLCoreIdentical()throws Exception {
    String myControlXML =
        "<struct><int>3</int><boolean>false</boolean></struct>";
    String myTestXML =
        "<struct><boolean>false</boolean><int>3</int></struct>";
		
    Diff myDiffSimilar = DiffBuilder.compare(myControlXML).withTest(myTestXML)
     .checkForSimilar()
     .build();
	assertFalse("XML similar " + myDiffSimilar.toString(), myDiffSimilar.hasDifferences());
	
    Diff myDiffIdentical = DiffBuilder.compare(myControlXML).withTest(myTestXML)
     .checkForIdentical()
     .build();
	assertFalse("XML identical " + myDiffIdentical.toString(), myDiffIdentical.hasDifferences());
}

New XMLUnit 2.x Code with xmlunit-matchers:

public void testXMLMatchersIdentical()throws Exception {
    String myControlXML =
        "<struct><int>3</int><boolean>false</boolean></struct>";
    String myTestXML =
        "<struct><boolean>false</boolean><int>3</int></struct>";
		
	assertThat(myTestXML, CompareMatcher.isSimilarTo(myControlXML));
	assertThat(myTestXML, CompareMatcher.isIdenticalTo(myControlXML));
}

Old XMLUnit 1.x DetailedDiff

In XmlUnit 2.x there is no DetailedDiff. The new Diff Object already contains all differences per default.

Old code:

DetailedDiff myDiff = new DetailedDiff(new Diff(myControlXML, myTestXML));
List allDifferences = myDiff.getAllDifferences();
assertEquals(myDiff.toString(), 2, allDifferences.size());

New Code

Diff myDiff = DiffBuilder.compare(myControlXML).withTest(myTestXML).build();
Iterable<Difference> differences = myDiff.getDifferences()
while(differences.hasNext()) {
	System.out(differences.next().toString());
}

The behaviour in XMlUnit 2.x is inverted. If you want stop comparision after first found difference, you must set a ComparisonController:

DiffBuilder.withComparisonController(ComparisonControllers.StopWhenDifferent)

Migrate custom XMLUnit 1.x DifferenceListener to the XMLUnit 2.x DifferenceEvaluator

The old DifferenceListener interface...

public interface DifferenceListener {
	...
	int differenceFound(Difference difference);
	...
}

...is replaces by the new DifferenceEvaluator interface:

public interface DifferenceEvaluator {
    ComparisonResult evaluate(Comparison comparison, ComparisonResult outcome);
}

changed Features in DifferenceEvaluator

XMLUnit 1.x	XMLUnit 2.x
difference.getControlNodeDetail().getNode()	comparison.getControlDetails().getTarget()
difference.getControlNodeDetail().getValue()	comparison.getControlDetails().getValue()
difference.getControlNodeDetail().getXpathLocation()	comparison.getControlDetails().getXPath()
difference.getTestNodeDetail()	comparison.getTestDetails()
difference.getDescription()	e.g: new DefaultComparisonFormatter().getDescription(comparison)
difference.isRecoverable()	you now get the ComparisonResult enum as separate paramter. If you need check for ComparisonResult.SIMILAR, you must chain your DifferenceEvaluator with the default evaluator (see example below).
difference.getId()	is now an enum: comparison.getType()

With XMLUnit 2.x you can chain multiple DifferenceEvaluators and handle it as one:

DifferenceEvaluator chainedEvaluator = DifferenceEvaluators.chain(
             DifferenceEvaluators.Default, new MyDifferenceEvaluator());

DifferenceEvaluators.chain() will pass the outcome from one evaluator to the next evaluator. In this case, the "MyDifferenceEvaluator" can also check if the previous outcome was ComparisonResult.SIMILAR.

DifferenceListener to DifferenceEvaluator migration Example:

Migrate custom XMLUnit 1.x ElementQualifier to the XMLUnit 2.x ElementSelector

The XMLUnit 1.x ElementQualifier is replaced by the NodeMatcher. But for migration from the old ElementQualifier it's best to implement a ElementSelector for the DefaultNodeMatcher:

NodeMatcher nodeMatcher = new DefaultNodeMatcher(new MyElementSelector()):

The Interfaces of the old ElementQualifiere and the new ElementSelector are very similar: ElementQualifier:

boolean qualifyForComparison(Element control, Element test); 

ElementSelector:

boolean canBeCompared(Element controlElement, Element testElement);

ElementQualifier to ElementSelector migration Example: