by xmlunit

xmlunit / xmlunit

XMLUnit for Java 2.x

222 Stars 57 Forks Last release: 5 months ago (v2.7.0) Apache License 2.0 909 Commits 18 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

XMLUnit for Java 2.x

Maven Central

Build Status XMLUnit 2.x for Java Coverage Status

XMLUnit is a library that supports testing XML output in several ways.

XMLUnit 2.x is a complete rewrite of XMLUnit and actually doesn't share any code with XMLUnit for Java 1.x.

Some goals for XMLUnit 2.x:

  • create .NET and Java versions that are compatible in design while trying to be idiomatic for each platform
  • remove all static configuration (the old XMLUnit class setter methods)
  • focus on the parts that are useful for testing
    • XPath
    • (Schema) validation
    • comparisons
  • be independent of any test framework

Even though active development happens for XMLUnit 2.x, XMLUnit 1.x for Java is still supported and will stay at sourceforge.


Help Wanted!

If you are looking for something to work on, we've compiled a list of known issues.

Please see the contributing guide for details on how to contribute.

Latest Release

The latest releases are available as GitHub releases or via Maven Central.

The core library is



We are providing SNAPSHOT builds from Sonatypes OSS Nexus Repository, you need to add


to your Maven settings.


These are some really small examples, more is available as part of the user guide

Comparing Two Documents

Source control = Input.fromFile("test-data/good.xml").build();
Source test = Input.fromByteArray(createTestDocument()).build();
DifferenceEngine diff = new DOMDifferenceEngine();
diff.addDifferenceListener(new ComparisonListener() {
        public void comparisonPerformed(Comparison comparison, ComparisonResult outcome) {
            Assert.fail("found a difference: " + comparison);
diff.compare(control, test);

or using the fluent builder API

Diff d = DiffBuilder.compare(Input.fromFile("test-data/good.xml"))
assert !d.hasDifferences();

or using Hamcrest with

import static org.xmlunit.matchers.CompareMatcher.isIdenticalTo;

assertThat(createTestDocument(), isIdenticalTo(Input.fromFile("test-data/good.xml")));

or using AssertJ with

import static org.xmlunit.assertj.XmlAssert.assertThat;

assertThat(createTestDocument()) .and(Input.fromFile("test-data/good.xml")) .areIdentical();

Asserting an XPath Value

Source source = Input.fromString("bar").build();
XPathEngine xpath = new JAXPXPathEngine();
Iterable allMatches = xpath.selectNodes("/foo", source);
assert allMatches.iterator().hasNext();
String content = xpath.evaluate("/foo/text()", source);
assert "bar".equals(content);

or using Hamcrest with

assertThat("bar", HasXPathMatcher.hasXPath("/foo"));
assertThat("bar", EvaluateXPathMatcher.hasXPath("/foo/text()",

or using AssertJ with

import static org.xmlunit.assertj.XmlAssert.assertThat;

assertThat("bar").hasXPath("/foo"); assertThat("bar").valueByXPath("/foo/text()").isEqualTo("bar");

Validating a Document Against an XML Schema

Validator v = Validator.forLanguage(Languages.W3C_XML_SCHEMA_NS_URI);
ValidationResult result = v.validateInstance(Input.fromDocument(createDocument()).build());
boolean valid = result.isValid();
Iterable problems = result.getProblems();

or using Hamcrest with

import static org.xmlunit.matchers.ValidationMatcher.valid;

assertThat(createDocument(), valid(Input.fromFile("local.xsd")));

or using AssertJ with

import static org.xmlunit.assertj.XmlAssert.assertThat;



Starting with version 2.8.0 XMLUnit requires Java 7, which has always been the minimum requirement for the AssertJ module. All other modules in versions 2.0.0 to 2.7.0 required Java 6.


library provides all functionality needed to test XML output and hasn't got any dependencies. It uses JUnit 4.x for its own tests.

If you are using Java 9 or later the core also depends on the JAXB API. This used to be part of the standard class library but has been split out of it with Java 9.

If you want to use

- i.e. you want to serialize plain Java objects to XML as input - then you also need to add a dependency on the JAXB implementation. Starting with XMLUnit 2.6.4, xmlunit-core optionally depends on the JAXB reference implementation and its transitive dependencies. Starting with XMLUnit 2.8.0 the JAXB dependency requires the JakartaEE version of JAXB.

The core library is complemented by Hamcrest 1.x matchers and AssertJ assertions. There also exists a

project that provides the API of XMLUnit 1.x on top of the 2.x core library.

While the Hamcrest matchers are built against Hamcrest 1.x they are supposed to work with Hamcrest 2.x as well.

Checking out XMLUnit for Java

XMLUnit for Java uses a git submodule for test resources it shares with XMLUnit.NET. You can either clone this repository using

clone --recursive
or run
git submodule update --init
inside your fresh working copy after cloning normally.

If you have checked out a working copy before we added the submodule, you'll need to run

git submodule update --init


XMLUnit for Java builds using Apache Maven 3.x, mainly you want to run

$ mvn install

in order to compile all modules and run the tests.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.