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
```