XMLUnit Core is a comprehensive XML testing library for Java that provides powerful tools for comparing XML documents, validating XML against schemas, and evaluating XPath expressions.
npx @tessl/cli install tessl/maven-org-xmlunit--xmlunit-core@2.10.0XMLUnit Core is a comprehensive XML testing library for Java that provides powerful tools for comparing XML documents, validating XML against schemas, and evaluating XPath expressions. The library supports various XML comparison strategies including structural comparisons, difference detection with customizable evaluation rules, and flexible node matching algorithms.
<dependency>
<groupId>org.xmlunit</groupId>
<artifactId>xmlunit-core</artifactId>
<version>2.10.0</version>
</dependency>import org.xmlunit.builder.Input;
import org.xmlunit.builder.DiffBuilder;
import org.xmlunit.diff.Diff;
import org.xmlunit.validation.Validator;
import org.xmlunit.xpath.JAXPXPathEngine;Common builder classes:
import org.xmlunit.builder.Transform;
import org.xmlunit.builder.DifferenceEngineConfigurer;Utility classes:
import org.xmlunit.util.Convert;
import org.xmlunit.util.IterableNodeList;
import org.xmlunit.util.Nodes;
import org.xmlunit.util.Predicate;import org.xmlunit.builder.Input;
import org.xmlunit.builder.DiffBuilder;
import org.xmlunit.diff.Diff;
// Compare two XML documents
Source control = Input.fromFile("expected.xml").build();
Source test = Input.fromString("<root><element>value</element></root>").build();
Diff diff = DiffBuilder.compare(control)
.withTest(test)
.checkForSimilar()
.build();
boolean identical = !diff.hasDifferences();
// Validate XML against schema
Validator validator = Validator.forLanguage(Languages.W3C_XML_SCHEMA_NS_URI);
validator.setSchemaSources(Input.fromFile("schema.xsd").build());
ValidationResult result = validator.validateInstance(Input.fromString(xmlContent).build());
boolean isValid = result.isValid();
// Evaluate XPath expressions
Source xmlSource = Input.fromString("<users><user id='1'>John</user></users>").build();
JAXPXPathEngine xpath = new JAXPXPathEngine();
String userName = xpath.evaluate("/users/user[@id='1']/text()", xmlSource);XMLUnit Core is built around several key components:
Input builder for creating XML sources from files, strings, streams, DOM documents, and other formatsDiffBuilder, Transform) for configuring complex operationsThe library is framework-agnostic and serves as the foundation for testing integrations with JUnit, Hamcrest, and AssertJ.
Core XML comparison functionality for detecting structural differences, content variations, and attribute changes between XML documents. Supports ignore patterns, custom difference evaluators, and detailed difference reporting.
public static DiffBuilder compare(Source control);
public class Diff {
public boolean hasDifferences();
public Iterable<Difference> getDifferences();
}
public class DiffBuilder {
public DiffBuilder withTest(Source test);
public DiffBuilder ignoreWhitespace();
public DiffBuilder ignoreComments();
public DiffBuilder normalizeWhitespace();
public DiffBuilder withDifferenceEvaluator(DifferenceEvaluator evaluator);
public DiffBuilder withNodeMatcher(NodeMatcher matcher);
public Diff build();
}Flexible input source creation and transformation for XML documents from various formats including files, strings, streams, DOM documents, and JAXB objects.
public class Input {
public static Builder fromFile(File file);
public static Builder fromFile(String fileName);
public static Builder fromString(String s);
public static Builder fromStream(InputStream s);
public static Builder fromByteArray(byte[] b);
public static Builder fromDocument(Document d);
public static Builder fromNode(Node n);
public static Builder fromURI(String uri);
public static Builder fromURL(URL url);
public static Builder fromJaxb(Object jaxbObject);
}
public interface Builder {
public Source build();
}XML validation against various schema languages including W3C XML Schema, RelaxNG, and Schematron with detailed validation error reporting and custom error handling.
public static Validator forLanguage(String language);
public class Validator {
public void setSchemaSources(Source... schemaSources);
public ValidationResult validateInstance(Source instance);
}
public class ValidationResult {
public boolean isValid();
public Iterable<ValidationProblem> getProblems();
}
public class Languages {
public static final String W3C_XML_SCHEMA_NS_URI;
public static final String XML_DTD_NS_URI;
public static final String RELAXNG_NS_URI;
}XPath 1.0 expression evaluation with namespace support, custom XPath functions, and various return type handling for node sets, strings, numbers, and booleans.
public class JAXPXPathEngine implements XPathEngine {
public String evaluate(String xPath, Source s);
public Iterable<Node> selectNodes(String xPath, Source s);
public void setNamespaceContext(NamespaceContext ctx);
public void setXPathFunctionResolver(XPathFunctionResolver resolver);
}
public interface XPathEngine {
public String evaluate(String xPath, Source s);
public Iterable<Node> selectNodes(String xPath, Source s);
}XSLT stylesheet transformation utilities with parameter support, custom URI resolvers, and flexible output configuration for transforming XML documents.
public class Transform {
public static Builder source(Source s);
}
public interface Builder {
public Builder usingStylesheet(Source s);
public Builder withParameter(String name, Object value);
public Builder withOutputProperty(String name, String value);
public TransformationResult build();
}Helper utilities for converting between different XML representations and working with DOM nodes.
public class Convert {
public static Document toDocument(Source s);
public static Document toDocument(Source s, DocumentBuilderFactory factory);
public static Node toNode(Source s);
public static Node toNode(Source s, DocumentBuilderFactory factory);
public static InputSource toInputSource(Source s);
public static InputSource toInputSource(Source s, TransformerFactory factory);
public static NamespaceContext toNamespaceContext(Map<String, String> prefix2URI);
}
public class IterableNodeList implements Iterable<Node> {
public IterableNodeList(NodeList nl);
// Makes NodeList iterable in for-each loops
}
public class Nodes {
public static QName getQName(Node n);
public static String getMergedNestedText(Node n);
public static Map<QName, String> getAttributes(Node n);
public static Map<QName, String> getAttributes(Node n, Predicate<Attr> attributeFilter);
}
public interface Predicate<T> {
boolean test(T toTest);
}These utilities are primarily used internally by XMLUnit but are available for advanced use cases requiring XML format conversions.
XMLUnit Core defines a hierarchy of exceptions for different error conditions:
public class XMLUnitException extends RuntimeException {
public XMLUnitException(String message);
public XMLUnitException(String message, Throwable cause);
public XMLUnitException(Throwable cause);
}
public class ConfigurationException extends XMLUnitException {
public ConfigurationException(String message, Throwable cause);
public ConfigurationException(Throwable cause);
}Common exception scenarios:
ConfigurationException: JAXP configuration issues, missing schema parsersXMLUnitException: General XML processing errors, transformation failuresIOException for file operations, SAXException for XML parsing// Core comparison types
public enum ComparisonType {
ATTR_NAME_LOOKUP, ATTR_VALUE, CHILD_LOOKUP, CHILD_NODELIST_LENGTH,
CHILD_NODELIST_SEQUENCE, ELEMENT_NAME, ELEMENT_TAG_NAME, HAS_DOCTYPE_DECLARATION,
NAMESPACE_PREFIX, NAMESPACE_URI, NODE_TYPE, NO_NAMESPACE_SCHEMA_LOCATION,
PROCESSING_INSTRUCTION_DATA, PROCESSING_INSTRUCTION_TARGET, SCHEMA_LOCATION,
TEXT_VALUE, XML_VERSION, XML_STANDALONE, XML_ENCODING, DOCTYPE_NAME,
DOCTYPE_PUBLIC_ID, DOCTYPE_SYSTEM_ID, COMMENT_VALUE, CDATA_VALUE
}
public enum ComparisonResult {
EQUAL, SIMILAR, DIFFERENT
}
// Input and transformation types
public interface Source extends javax.xml.transform.Source {
// Extends standard JAXP Source interface
}
// Validation types
public enum ValidationProblem.ProblemType {
ERROR, WARNING
}