or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

comparison.mdindex.mdinput.mdtransform.mdvalidation.mdxpath.md
tile.json

tessl/maven-org-xmlunit--xmlunit-core

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.xmlunit/xmlunit-core@2.10.x

To install, run

npx @tessl/cli install tessl/maven-org-xmlunit--xmlunit-core@2.10.0

index.mddocs/

XMLUnit Core

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. The library supports various XML comparison strategies including structural comparisons, difference detection with customizable evaluation rules, and flexible node matching algorithms.

Package Information

  • Package Name: org.xmlunit:xmlunit-core
  • Package Type: maven
  • Language: Java
  • Installation: Maven dependency
  • Version: 2.10.0
  • License: Apache-2.0
  • Documentation: https://github.com/xmlunit/user-guide/wiki
<dependency>
  <groupId>org.xmlunit</groupId>
  <artifactId>xmlunit-core</artifactId>
  <version>2.10.0</version>
</dependency>

Core Imports

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;

Basic Usage

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

Architecture

XMLUnit Core is built around several key components:

  • Input Sources: Flexible Input builder for creating XML sources from files, strings, streams, DOM documents, and other formats
  • Difference Engine: Core comparison engine with customizable difference evaluators and node matchers
  • Fluent Builders: Comprehensive builder pattern APIs (DiffBuilder, Transform) for configuring complex operations
  • Validation System: Schema validation support for W3C XML Schema, RelaxNG, and other validation languages
  • XPath Engine: XPath 1.0 evaluation with namespace support and custom functions
  • Transformation: XSLT transformation utilities with parameter support

The library is framework-agnostic and serves as the foundation for testing integrations with JUnit, Hamcrest, and AssertJ.

Capabilities

XML Document Comparison

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();
}

XML Comparison

Input Source Management

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();
}

Input Sources

Schema Validation

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

Schema Validation

XPath Evaluation

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);
}

XPath Evaluation

XSLT Transformation

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();
}

XSLT Transformation

XML Utilities

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.

Exception Handling

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 parsers
  • XMLUnitException: General XML processing errors, transformation failures
  • Standard Java exceptions: IOException for file operations, SAXException for XML parsing

Types

// 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
}