1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.Using XMLUnit</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="XMLUnit Java User's Guide"><link rel="up" href="index.html" title="XMLUnit Java User's Guide"><link rel="prev" href="index.html" title="XMLUnit Java User's Guide"><link rel="next" href="ar01s03.html" title="3.Comparing Pieces of XML"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2.Using XMLUnit</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a></td><th width="60%" align="center"></th><td width="20%" align="right"><a accesskey="n" href="ar01s03.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Using%20XMLUnit"></a>2.Using XMLUnit</h2></div></div></div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="Requirements"></a>2.1.Requirements</h3></div></div></div>
<p>XMLUnit requires a JAXP compliant XML parser virtually
everywhere. Several features of XMLUnit also require a JAXP
compliant XSLT transformer. If it is available, a JAXP
compliant XPath engine will be used for XPath tests.</p>
<p>To build XMLUnit at least JAXP 1.2 is required, this is
the version provided by the Java class library in JDK 1.4. The
JAXP 1.3 (i.e. Java5 and above) XPath engine can only be built
when JAXP 1.3 is available.</p>
<p>As long as you don't require support for XML Namespaces or
XML Schema, any JAXP 1.1 compliant implementations should work
at runtime. For namespace and schema support you will need a
parser that complies to JAXP 1.2 and supports the required
feature. The XML parser shipping with JDK 1.4 (a version of
Apache Crimson) for example is compliant to JAXP 1.2 but doesn't
support Schema validation.</p>
<p>XMLUnit is supposed to build and run on any Java version
after 1.3 (at least no new hard JDK 1.4 dependencies have been
added in XMLUnit 1.1), but it has only been tested on JDK 1.4.2
and above.</p>
<p>To build XMLUnit JUnit 3.x (only tested with JUnit 3.8.x)
is required. It is not required at runtime unless you intend to
use the <code class="literal">XMLTestCase</code> or
<code class="literal">XMLAssert</code> classes.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="Basic%20Usage"></a>2.2.Basic Usage</h3></div></div></div>
<p>XMLUnit consists of a few classes all living in the
<code class="literal">org.custommonkey.xmlunit</code> package. You can
use these classes directly from your code, no matter whether you
are writing a unit test or want to use XMLUnit's features for
any other purpose.</p>
<p>This section provides a few hints of where to start if you
want to use a certain feature of XMLUnit, more details can be
found in the more specific sections later in this
document.</p>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="Basic:%20Comparing%20Pieces%20of%20XML"></a>2.2.1.Comparing Pieces of XML</h4></div></div></div>
<p>Heart and soul of XMLUnit's comparison engine is
<code class="literal">DifferenceEngine</code> but most of the time you
will use it indirectly via the <code class="literal">Diff</code>
class.</p>
<p>You can influence the engine by providing (custom)
implementations for various interfaces and by setting a couple
of options on the <code class="literal">XMLUnit</code> class.</p>
<p>More information is available in <a class="xref" href="ar01s03.html" title="3.Comparing Pieces of XML">Section3, “Comparing Pieces of XML”</a>.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="Basic:%20Validating"></a>2.2.2.Validating</h4></div></div></div>
<p>All validation happens in the
<code class="literal">Validator</code> class. The default is to
validate against a DTD, but XML Schema validation can be
enabled by an option (see
<code class="literal">Validator.useXMLSchema</code>).</p>
<p>Several options of the <code class="literal">XMLUnit</code> class
affect validation.</p>
<p>More information is available in <a class="xref" href="ar01s04.html" title="4.Validating XML Documents">Section4, “Validating XML Documents”</a>.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="XSLT%20Transformations"></a>2.2.3.XSLT Transformations</h4></div></div></div>
<p>The <code class="literal">Transform</code> class provides an easy
to use layer on top of JAXP's transformations. An instance of
this class is initialized with the source document and a
stylesheet and the result of the transformation can be
retrieved as a <code class="literal">String</code> or DOM
<code class="literal">Document</code>.</p>
<p>The output of <code class="literal">Transform</code> can be used
as input to comparisons, validations, XPath tests and so on.
There is no detailed sections on transformations since they
are really only a different way to create input for the rest
of XMLUnit's machinery. Examples can be found in <a class="xref" href="index.html#Comparing%20XML%20Transformations" title="1.6.Comparing XML Transformations">Section1.6, “Comparing XML Transformations”</a>.</p>
<p>It is possible to provide a custom
<code class="literal">javax.xml.transform.URIResolver</code> via the
<code class="literal">XMLUnit.setURIResolver</code> method.</p>
<p>You can access the underlying XSLT transformer via
<code class="literal">XMLUnit.getTransformerFactory</code>.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="XPath%20Engine"></a>2.2.4.XPath Engine</h4></div></div></div>
<p>The central piece of XMLUnit's XPath support is the
<code class="literal">XpathEngine</code> interface. Currently two
implementations of the interface exist,
<code class="literal">SimpleXpathEngine</code> and
<code class="literal">org.custommonkey.xmlunit.jaxp13.Jaxp13XpathEngine</code>.</p>
<p><code class="literal">SimpleXpathEngine</code> is a very basic
implementation that uses your XSLT transformer under the
covers. This also means it will expose you to the bugs found
in your transformer like the transformer claiming a stylesheet
couldn't be compiled for very basic XPath expressions. This
has been reported to be the case for JDK 1.5.</p>
<p><code class="literal">org.custommonkey.xmlunit.jaxp13.Jaxp13XpathEngine</code>
uses JAXP 1.3's <code class="literal">javax.xml.xpath</code> package and
seems to work more reliable, stable and performant than
<code class="literal">SimpleXpathEngine</code>.</p>
<p>You use the <code class="literal">XMLUnit.newXpathEngine</code>
method to obtain an instance of the
<code class="literal">XpathEngine</code>. As of XMLUnit 1.1 this will
try to use JAXP 1.3 if it is available and fall back to
<code class="literal">SimpleXpathEngine</code>.</p>
<p>Instances of <code class="literal">XpathEngine</code> can return
the results of XPath queries either as DOM
<code class="literal">NodeList</code> or plain
<code class="literal">String</code>s.</p>
<p>More information is available in <a class="xref" href="ar01s05.html" title="5.XPath Tests">Section5, “XPath Tests”</a>.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="Basic:%20DOM%20Tree%20Walking"></a>2.2.5.DOM Tree Walking</h4></div></div></div>
<p>To test pieces of XML by traversing the DOM tree you use
the <code class="literal">NodeTester</code> class. Each DOM
<code class="literal">Node</code> will be passed to a
<code class="literal">NodeTester</code> implementation you provide. The
<code class="literal">AbstractNodeTester</code> class is provided as a
NullObject Pattern base class for implementations of your
own.</p>
<p>More information is available in <a class="xref" href="ar01s06.html" title="6.DOM Tree Walking">Section6, “DOM Tree Walking”</a>.</p>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="Using%20XMLUnit%20With%20JUnit%203.x"></a>2.3.Using XMLUnit With JUnit 3.x</h3></div></div></div>
<p>Initially XMLUnit was tightly coupled to JUnit and the
recommended approach was to write unit tests by inheriting from
the <code class="literal">XMLTestCase</code> class.
<code class="literal">XMLTestCase</code> provides a pretty long list of
<code class="literal">assert...</code> methods that may simplify your
interaction with XMLUnit's internals in many common
cases.</p>
<p>The <code class="literal">XMLAssert</code> class provides the same
set of <code class="literal">assert...</code>s as static methods. Use
<code class="literal">XMLAssert</code> instead of
<code class="literal">XMLTestCase</code> for your unit tests if you can't
or don't want to inherit from
<code class="literal">XMLTestCase</code>.</p>
<p>All power of XMLUnit is available whether you use
<code class="literal">XMLTestCase</code> and/or
<code class="literal">XMLAssert</code> or the underlying API directly. If
you are using JUnit 3.x then using the specific classes may prove
to be more convenient.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="Common%20Configuration%20Options"></a>2.4.Common Configuration Options</h3></div></div></div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="JAXP"></a>2.4.1.JAXP</h4></div></div></div>
<p>If you are using a JDK 1.4 or later, your Java class
library already contains the required XML parsers and XSLT
transformers. Still you may want to use a different
parser/transformer than the one of your JDK - in particular
since the versions shipping with some JDKs are known to
contain serious bugs.</p>
<p>As described in <a class="xref" href="index.html#Configuring%20XMLUnit" title="1.4.Configuring XMLUnit">Section1.4, “Configuring XMLUnit”</a>
there are two main approaches to choose the XML parser of XSLT
transformer: System properties and setters in the
<code class="literal">XMLUnit</code> class.</p>
<p>If you use system properties you have the advantage that
your choice affects the whole JAXP system, whether it is used
inside of XMLUnit or not. If you are using JDK 1.4 or later
you may also want to review the <a class="ulink" href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/" target="_top">Endorsed
Standards Override Mechanism</a> to use a different
parser/transformer than the one shipping with your JDK.</p>
<p>The second option - using the <code class="literal">XMLUnit</code>
class - allows you to use different parsers for control and
test documents, it even allows you to use different parsers
for different test cases, if you really want to stretch it
that far. It may also work for JDK 1.4 and above, even if you
don't override the endorsed standards libraries.</p>
<p>You can access the underlying JAXP parser by
<code class="literal">XMLUnit.newControlParser</code>,
<code class="literal">XMLUnit.newTestParser</code>,
<code class="literal">XMLUnit.getControlDocumentBuilderFactory</code>,
<code class="literal">XMLUnit.getTestDocumentBuilderFactory</code> and
<code class="literal">XMLUnit.getSAXParserFactory</code> (used by
<code class="literal">Validator</code>). Note that all these methods
return factories or parsers that are namespace aware.</p>
<p>The various <code class="literal">build...</code> methods in
<code class="literal">XMLUnit</code> provide convenience layers for
building DOM <code class="literal">Document</code>s using the configured
parsers.</p>
<p>You can also set the class name for the
<code class="literal">XPathFactory</code> to use when using JAXP 1.3 by
passing the class name to
<code class="literal">XMLUnit.setXPathFactory</code>.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="EntityResolver"></a>2.4.2.<code class="literal">EntityResolver</code></h4></div></div></div>
<p>You can provide a custom
<code class="literal">org.xml.sax.EntityResolver</code> for the control
and test parsers via
<code class="literal">XMLUnit.setControlEntityResolver</code> and
<code class="literal">XMLUnit.setTestEntityResolver</code>.
<code class="literal">Validator</code> uses the resolver set via
<code class="literal">setControlEntityResolver</code> as well.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="Basic:%20Element%20Content%20Whitespace"></a>2.4.3.Element Content Whitespace</h4></div></div></div>
<p>Element content whitespace - also known as ignorable
whitespace - is whitespace contained in elements whose content
model doesn't allow text content. I.e. the newline and space
characters between <code class="literal"><foo></code> and
<code class="literal"><bar></code> in the following example
could belong into this category.</p>
<pre class="programlisting">
<foo>
<bar/></foo>
</pre>
<p>Using <code class="literal">XMLUnit.setIgnoreWhitespace</code> it
is possible to make the test and control parser ignore this
kind of whitespace.</p>
<p>Note that setting this property to
<code class="literal">true</code> usually doesn't have any effect since
it only works on validating parsers and XMLUnit doesn't enable
validation by default. It does have an effect when comparing
pieces of XML, though, since the same flag is used for a
different purpose as well in that case. See <a class="xref" href="ar01s03.html#Whitespace%20Handling" title="3.8.1.Whitespace Handling">Section3.8.1, “Whitespace Handling”</a> for more details.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="XSLT%20Stylesheet%20Version"></a>2.4.4.XSLT Stylesheet Version</h4></div></div></div>
<p>Some features of XMLUnit use XSLT stylesheets under the
covers, in particular XSLT will be used to strip element
content whitespace or comments as well as by
<code class="literal">SimpleXpathEngine</code>. These stylesheets only
require a XSLT transformer that supports XSLT 1.0 and will say
so in the <code class="literal">stylesheet</code> element.</p>
<p>If your XSLT transformer supports XSLT 2.0 or newer it
may<a href="#ftn.idp42609744" class="footnote" name="idp42609744"><sup class="footnote">[6]</sup></a> issue a warning for these stylesheets
which can be annoying. You can use
<code class="literal">XMLUnit.setXSLTVersion</code> to make XMLUnit
change the version attribute to a different value. Note that
XMLUnit hasn't been tested with a value other than
<code class="literal">"1.0"</code>.</p>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="Providing%20Input%20to%20XMLUnit"></a>2.5.Providing Input to XMLUnit</h3></div></div></div>
<p>Most methods in XMLUnit that expect a piece of XML as
input provide several overloads that obtain their input from
different sources. The most common options are:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">A DOM <code class="literal">Document</code>.
<p>Here you have all control over the document's
creation. Such a <code class="literal">Document</code> could as well
be the result of an XSLT transformation via the
<code class="literal">Transform</code> class.</p>
</li><li class="listitem">A SAX <code class="literal">InputSource</code>.
<p>This is the most generic way since
<code class="literal">InputSource</code> allows you to read from
arbitrary <code class="literal">InputStream</code>s or
<code class="literal">Reader</code>s. Use an
<code class="literal">InputStream</code> wrapped by an
<code class="literal">InputSource</code> if you want the XML parser to
pick up the proper encoding from the XML declaration.</p>
</li><li class="listitem">A <code class="literal">String</code>.
<p>Here a DOM <code class="literal">Document</code> is built from
the input <code class="literal">String</code> using the JAXP parser
specified for control or test documents - depending on
whether the input is a control or test piece of XML.</p>
<p>Note that using a <code class="literal">String</code> assumes
that your XML has already been converted from its XML
encoding to a Java <code class="literal">String</code> upfront.</p>
</li><li class="listitem">A <code class="literal">Reader</code>.
<p>Here a DOM <code class="literal">Document</code> is built from
the input <code class="literal">Reader</code> using the JAXP parser
specified for control or test documents - depending on
whether the input is a control or test piece of XML.</p>
<p>Note that using a <code class="literal">Reader</code> is a
bad choice if your XML encoding is different from your
platform's default encoding since Java's IO system won't
read your XML declaration. It is a good practice to use one
of the other overloads rather than the
<code class="literal">Reader</code> version to ensure encoding has
been dealt with properly.</p>
</li></ul></div>
</div>
<div class="footnotes"><br><hr style="width:100; text-align:left;margin-left: 0"><div id="ftn.idp42609744" class="footnote"><p><a href="#idp42609744" class="para"><sup class="para">[6] </sup></a>The W3C recommendation says it
SHOULD.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a></td><td width="20%" align="center"></td><td width="40%" align="right"><a accesskey="n" href="ar01s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">XMLUnit Java User's Guide</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">3.Comparing Pieces of XML</td></tr></table></div></body></html>
|
