0
# XMLUnit Core
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: org.xmlunit:xmlunit-core
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Maven dependency
10
- **Version**: 2.10.0
11
- **License**: Apache-2.0
12
- **Documentation**: https://github.com/xmlunit/user-guide/wiki
13

14
```xml
15
<dependency>
16
  <groupId>org.xmlunit</groupId>
17
  <artifactId>xmlunit-core</artifactId>
18
  <version>2.10.0</version>
19
</dependency>
20
```
21

22
## Core Imports
23

24
```java
25
import org.xmlunit.builder.Input;
26
import org.xmlunit.builder.DiffBuilder;
27
import org.xmlunit.diff.Diff;
28
import org.xmlunit.validation.Validator;
29
import org.xmlunit.xpath.JAXPXPathEngine;
30
```
31

32
Common builder classes:
33

34
```java
35
import org.xmlunit.builder.Transform;
36
import org.xmlunit.builder.DifferenceEngineConfigurer;
37
```
38

39
Utility classes:
40

41
```java
42
import org.xmlunit.util.Convert;
43
import org.xmlunit.util.IterableNodeList;
44
import org.xmlunit.util.Nodes;
45
import org.xmlunit.util.Predicate;
46
```
47

48
## Basic Usage
49

50
```java
51
import org.xmlunit.builder.Input;
52
import org.xmlunit.builder.DiffBuilder;
53
import org.xmlunit.diff.Diff;
54

55
// Compare two XML documents
56
Source control = Input.fromFile("expected.xml").build();
57
Source test = Input.fromString("<root><element>value</element></root>").build();
58

59
Diff diff = DiffBuilder.compare(control)
60
    .withTest(test)
61
    .checkForSimilar()
62
    .build();
63

64
boolean identical = !diff.hasDifferences();
65

66
// Validate XML against schema
67
Validator validator = Validator.forLanguage(Languages.W3C_XML_SCHEMA_NS_URI);
68
validator.setSchemaSources(Input.fromFile("schema.xsd").build());
69
ValidationResult result = validator.validateInstance(Input.fromString(xmlContent).build());
70
boolean isValid = result.isValid();
71

72
// Evaluate XPath expressions
73
Source xmlSource = Input.fromString("<users><user id='1'>John</user></users>").build();
74
JAXPXPathEngine xpath = new JAXPXPathEngine();
75
String userName = xpath.evaluate("/users/user[@id='1']/text()", xmlSource);
76
```
77

78
## Architecture
79

80
XMLUnit Core is built around several key components:
81

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

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

91
## Capabilities
92

93
### XML Document Comparison
94

95
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.
96

97
```java { .api }
98
public static DiffBuilder compare(Source control);
99

100
public class Diff {
101
    public boolean hasDifferences();
102
    public Iterable<Difference> getDifferences();
103
}
104

105
public class DiffBuilder {
106
    public DiffBuilder withTest(Source test);
107
    public DiffBuilder ignoreWhitespace();
108
    public DiffBuilder ignoreComments();
109
    public DiffBuilder normalizeWhitespace();
110
    public DiffBuilder withDifferenceEvaluator(DifferenceEvaluator evaluator);
111
    public DiffBuilder withNodeMatcher(NodeMatcher matcher);
112
    public Diff build();
113
}
114
```
115

116
[XML Comparison](./comparison.md)
117

118
### Input Source Management
119

120
Flexible input source creation and transformation for XML documents from various formats including files, strings, streams, DOM documents, and JAXB objects.
121

122
```java { .api }
123
public class Input {
124
    public static Builder fromFile(File file);
125
    public static Builder fromFile(String fileName);
126
    public static Builder fromString(String s);
127
    public static Builder fromStream(InputStream s);
128
    public static Builder fromByteArray(byte[] b);
129
    public static Builder fromDocument(Document d);
130
    public static Builder fromNode(Node n);
131
    public static Builder fromURI(String uri);
132
    public static Builder fromURL(URL url);
133
    public static Builder fromJaxb(Object jaxbObject);
134
}
135

136
public interface Builder {
137
    public Source build();
138
}
139
```
140

141
[Input Sources](./input.md)
142

143
### Schema Validation
144

145
XML validation against various schema languages including W3C XML Schema, RelaxNG, and Schematron with detailed validation error reporting and custom error handling.
146

147
```java { .api }
148
public static Validator forLanguage(String language);
149

150
public class Validator {
151
    public void setSchemaSources(Source... schemaSources);
152
    public ValidationResult validateInstance(Source instance);
153
}
154

155
public class ValidationResult {
156
    public boolean isValid();
157
    public Iterable<ValidationProblem> getProblems();
158
}
159

160
public class Languages {
161
    public static final String W3C_XML_SCHEMA_NS_URI;
162
    public static final String XML_DTD_NS_URI;
163
    public static final String RELAXNG_NS_URI;
164
}
165
```
166

167
[Schema Validation](./validation.md)
168

169
### XPath Evaluation
170

171
XPath 1.0 expression evaluation with namespace support, custom XPath functions, and various return type handling for node sets, strings, numbers, and booleans.
172

173
```java { .api }
174
public class JAXPXPathEngine implements XPathEngine {
175
    public String evaluate(String xPath, Source s);
176
    public Iterable<Node> selectNodes(String xPath, Source s);
177
    public void setNamespaceContext(NamespaceContext ctx);
178
    public void setXPathFunctionResolver(XPathFunctionResolver resolver);
179
}
180

181
public interface XPathEngine {
182
    public String evaluate(String xPath, Source s);
183
    public Iterable<Node> selectNodes(String xPath, Source s);
184
}
185
```
186

187
[XPath Evaluation](./xpath.md)
188

189
### XSLT Transformation
190

191
XSLT stylesheet transformation utilities with parameter support, custom URI resolvers, and flexible output configuration for transforming XML documents.
192

193
```java { .api }
194
public class Transform {
195
    public static Builder source(Source s);
196
}
197

198
public interface Builder {
199
    public Builder usingStylesheet(Source s);
200
    public Builder withParameter(String name, Object value);
201
    public Builder withOutputProperty(String name, String value);
202
    public TransformationResult build();
203
}
204
```
205

206
[XSLT Transformation](./transform.md)
207

208
### XML Utilities
209

210
Helper utilities for converting between different XML representations and working with DOM nodes.
211

212
```java { .api }
213
public class Convert {
214
    public static Document toDocument(Source s);
215
    public static Document toDocument(Source s, DocumentBuilderFactory factory);
216
    public static Node toNode(Source s);
217
    public static Node toNode(Source s, DocumentBuilderFactory factory);
218
    public static InputSource toInputSource(Source s);
219
    public static InputSource toInputSource(Source s, TransformerFactory factory);
220
    public static NamespaceContext toNamespaceContext(Map<String, String> prefix2URI);
221
}
222

223
public class IterableNodeList implements Iterable<Node> {
224
    public IterableNodeList(NodeList nl);
225
    // Makes NodeList iterable in for-each loops
226
}
227

228
public class Nodes {
229
    public static QName getQName(Node n);
230
    public static String getMergedNestedText(Node n);
231
    public static Map<QName, String> getAttributes(Node n);
232
    public static Map<QName, String> getAttributes(Node n, Predicate<Attr> attributeFilter);
233
}
234

235
public interface Predicate<T> {
236
    boolean test(T toTest);
237
}
238
```
239

240
These utilities are primarily used internally by XMLUnit but are available for advanced use cases requiring XML format conversions.
241

242
## Exception Handling
243

244
XMLUnit Core defines a hierarchy of exceptions for different error conditions:
245

246
```java { .api }
247
public class XMLUnitException extends RuntimeException {
248
    public XMLUnitException(String message);
249
    public XMLUnitException(String message, Throwable cause);
250
    public XMLUnitException(Throwable cause);
251
}
252

253
public class ConfigurationException extends XMLUnitException {
254
    public ConfigurationException(String message, Throwable cause);
255
    public ConfigurationException(Throwable cause);
256
}
257
```
258

259
Common exception scenarios:
260
- `ConfigurationException`: JAXP configuration issues, missing schema parsers
261
- `XMLUnitException`: General XML processing errors, transformation failures
262
- Standard Java exceptions: `IOException` for file operations, `SAXException` for XML parsing
263

264
## Types
265

266
```java { .api }
267
// Core comparison types
268
public enum ComparisonType {
269
    ATTR_NAME_LOOKUP, ATTR_VALUE, CHILD_LOOKUP, CHILD_NODELIST_LENGTH,
270
    CHILD_NODELIST_SEQUENCE, ELEMENT_NAME, ELEMENT_TAG_NAME, HAS_DOCTYPE_DECLARATION,
271
    NAMESPACE_PREFIX, NAMESPACE_URI, NODE_TYPE, NO_NAMESPACE_SCHEMA_LOCATION,
272
    PROCESSING_INSTRUCTION_DATA, PROCESSING_INSTRUCTION_TARGET, SCHEMA_LOCATION,
273
    TEXT_VALUE, XML_VERSION, XML_STANDALONE, XML_ENCODING, DOCTYPE_NAME,
274
    DOCTYPE_PUBLIC_ID, DOCTYPE_SYSTEM_ID, COMMENT_VALUE, CDATA_VALUE
275
}
276

277
public enum ComparisonResult {
278
    EQUAL, SIMILAR, DIFFERENT
279
}
280

281
// Input and transformation types
282
public interface Source extends javax.xml.transform.Source {
283
    // Extends standard JAXP Source interface
284
}
285

286
// Validation types
287
public enum ValidationProblem.ProblemType {
288
    ERROR, WARNING
289
}
290
```