Menu
▾
▴
SF.net SVN: xmlunit: [156] trunk/xmlunit/src/site/XMLUnit-Java.xml
|
From: <bo...@us...> - 2007-03-27 04:05:29
|
Revision: 156
http://xmlunit.svn.sourceforge.net/xmlunit/?rev=156&view=rev
Author: bodewig
Date: 2007-03-26 21:05:20 -0700 (Mon, 26 Mar 2007)
Log Message:
-----------
Using XMLUnit section added
Modified Paths:
--------------
trunk/xmlunit/src/site/XMLUnit-Java.xml
Modified: trunk/xmlunit/src/site/XMLUnit-Java.xml
===================================================================
--- trunk/xmlunit/src/site/XMLUnit-Java.xml 2007-03-23 20:01:39 UTC (rev 155)
+++ trunk/xmlunit/src/site/XMLUnit-Java.xml 2007-03-27 04:05:20 UTC (rev 156)
@@ -126,7 +126,7 @@
unrecoverable differences</emphasis> between them.</para>
</section>
- <section><title>Configuring XMLUnit</title>
+ <section id="configuring-intro"><title>Configuring XMLUnit</title>
<para>There are many Java XML parsers available, and XMLUnit
should work with any JAXP compliant parser library, such as
@@ -137,8 +137,8 @@
transformation engine is required, such as Xalan-J<footnote
id="xalan-link"><para><ulink
url="http://xalan.apache.org/">http://xalan.apache.org/</ulink></para></footnote>,
- from the Software Foundation. To configure XMLUnit to use a
- specific parser and transformation engine set three System
+ from the Apache Software Foundation. To configure XMLUnit to
+ use a specific parser and transformation engine set three System
properties before any tests are run, e.g.</para>
<example><title>Configuring JAXP via System Properties</title>
@@ -152,15 +152,9 @@
]]></programlisting>
</example>
- <para>If you are using a JDK 1.4 or later, your Java class
- library already contain 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. You may also want to review the <ulink
- url="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">Endorsed
- Standards Override Mechanism</ulink> to use a different
- parser/transformer than the one of your JDK.</para>
+ <para>You may want to read <xref linkend="JAXP"/> for more
+ details - in particular if you are using Java 1.4 or
+ later.</para>
<para>Alternatively there are static methods on the XMLUnit
class that can be called directly. The advantage of this
@@ -178,10 +172,6 @@
]]></programlisting>
</example>
- <para>The later approach should also work for JDK 1.4 and above,
- even if you don't override the endorsed standards
- libraries</para>
-
</section>
<section><title>Writing XML comparison tests</title>
@@ -386,7 +376,8 @@
</section>
- <section><title>Comparing XML Transformations</title>
+ <section id="transform-intro">
+ <title>Comparing XML Transformations</title>
<para>XMLUnit can test XSL transformations at a high level using
the <literal>Transform</literal> class that wraps an
@@ -667,20 +658,304 @@
<section id="Using"><title>Using XMLUnit</title>
+ <section id="requirements">
+ <title>Requirements</title>
+
+ <para>XMLUnit requires a JAXP compliant XML parser virtually
+ everywhere. Several features of XMLUnit also require a JAXP
+ compliant XSLT transformer. If it is avaliable, a JAXP
+ compliant XPath engine will be used for XPath tests.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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.</para>
+
+ <para>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 <literal>XMLTestCase</literal> or
+ <literal>XMLAssert</literal> classes.</para>
+ </section>
+
<section id="using-plain">
<title>Basic Usage</title>
- <section id="input-choices">
- <title>Providing Input to XMLUnit</title>
+ <para>XMLUnit consists of a few classes all living in the
+ <literal>org.custommonkey.xmlunit</literal> 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.</para>
+
+ <para>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.</para>
+
+ <section><title>Comparing Pieces of XML</title>
+
+ <para>Heart and soul of XMLUnit's comparison engine is
+ <literal>DifferenceEngine</literal> but most of the time you
+ will use it indirectly via the <literal>Diff</literal>
+ class.</para>
+
+ <para>You can influence the engine by providing (custom)
+ implementations for various interfaces and by setting a couple
+ of options on the <literal>XMLUnit</literal> class.</para>
+
+ <para>More information is available in <xref
+ linkend="Comparing"/>.</para>
+
</section>
+
+ <section><title>Validating</title>
+
+ <para>All validation happens in the
+ <literal>Validator</literal> class. The default is to
+ validate against a DTD, but XML Schema validation can be
+ enabled by an option (see
+ <literal>Validator.useXMLSchema</literal>).</para>
+
+ <para>Several options of the <literal>XMLUnit</literal> class
+ affect validation.</para>
+
+ <para>More information is available in <xref
+ linkend="Validating"/>.</para>
+
+ </section>
+
+ <section><title>XSLT Transformations</title>
+
+ <para>The <literal>Transform</literal> 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 <literal>String</literal> or DOM
+ <literal>Document</literal>.</para>
+
+ <para>The output of <literal>Transform</literal> can be used
+ as input to comparisions, 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 <xref
+ linkend="transform-intro"/>.</para>
+
+ <para>You can access the underlying XSLT transformer via
+ <literal>XMLUnit.getTransformerFactory</literal>.</para>
+ </section>
+
+ <section>
+ <title>XPath Engine</title>
+
+ <para>The central piece of XMLUnit's XPath support is the
+ <literal>XpathEngine</literal> interface. Currently two
+ implementations of the interface exist,
+ <literal>SimpleXpathEngine</literal> and
+ <literal>org.custommonkey.xmlunit.jaxp13.Jaxp13XpathEngine</literal>.</para>
+
+ <para><literal>SimpleXpathEngine</literal> 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.</para>
+
+ <para><literal>org.custommonkey.xmlunit.jaxp13.Jaxp13XpathEngine</literal>
+ uses JAXP 1.3's <literal>javax.xml.xpath</literal> package and
+ seems to work more reliable, stable and performant than
+ <literal>SimpleXpathEngine</literal>.</para>
+
+ <para>You use the <literal>XMLUnit.newXpathEngine</literal>
+ method to obtain an instance of the
+ <literal>XpathEngine</literal>. As of XMLUnit 1.1 this will
+ try to use JAXP 1.3 if it is available and fall back to
+ <literal>SimpleXpathEngine</literal>.</para>
+
+ <para>Instances of <literal>XpathEngine</literal> can return
+ the results of XPath queries either as DOM
+ <literal>NodeList</literal> or plain
+ <literal>String</literal>s.</para>
+
+ <para>More information is available in <xref
+ linkend="XPath"/>.</para>
+ </section>
+
+ <section>
+ <title>DOM Tree Walking</title>
+
+ <para>To test pieces of XML by traversing the DOM tree you use
+ the <literal>NodeTester</literal> class. Each DOm
+ <literal>Node</literal> will be passed to a
+ <literal>NodeTester</literal> implementation you provide. The
+ <literal>AbstractNodeTester</literal> class is provided as a
+ NullObject pattern base class for your implementations of your
+ own.</para>
+
+ <para>More information is available in <xref
+ linkend="NodeTest"/>.</para>
+ </section>
</section>
<section id="junit3">
<title>Using XMLUnit With JUnit 3.x</title>
+
+ <para>Initially XMLUnit was tightly coupled to JUnit and the
+ recommended approach was to write unit tests by inheriting from
+ <literal>XMLTestCase</literal>. <literal>XMLTestCase</literal>
+ provides a pretty long list of <literal>assert...</literal>
+ methods that may simplify your interaction with XMLUnit's
+ internals in many common cases.</para>
+
+ <para>The <literal>XMLAssert</literal> class provides the same
+ set of <literal>assert...</literal>s as static methods. Use
+ <literal>XMLAssert</literal> instead of
+ <literal>XMLTestCase</literal> for your unit tests if you can't
+ or don't want to inherit from
+ <literal>XMLTestCase</literal>.</para>
+
+ <para>All power of XMLUnit is available whether you use
+ <literal>XMLTestCase</literal> and/or
+ <literal>XMLAssert</literal> or the underlying API directly. If
+ you are using JUnit 3.x then using the specifc classes may prove
+ to be more convenient.</para>
+
</section>
+
+ <section id="common-config">
+ <title>Common Configuration Options</title>
+
+ <section id="JAXP">
+ <title>JAXP</title>
+
+ <para>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.</para>
+
+ <para>As described in <xref linkend="configuring-intro"/>
+ there are two main approaches to choose the XML parser of XSLT
+ transformer: System properties and setters in the
+ <literal>XMLUnit</literal> class.</para>
+
+ <para>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 <ulink
+ url="http://java.sun.com/j2se/1.4.2/docs/guide/standards/">Endorsed
+ Standards Override Mechanism</ulink> to use a different
+ parser/transformer than the one shipping with your JDK.</para>
+
+ <para>The second option - using the <literal>XMLUnit</literal>
+ 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.</para>
+
+ <para>You can access the underlying JAXP parser by
+ <literal>XMLUnit.newControlParser</literal>,
+ <literal>XMLUnit.newTestParser</literal>,
+ <literal>XMLUnit.getControlDocumentBuilderFactory</literal>,
+ <literal>XMLUnit.getTestDocumentBuilderFactory</literal> and
+ <literal>XMLUnit.getSAXParserFactory</literal> (used by
+ Validator). The various <literal>build...</literal> methods
+ in <literal>XMLUnit</literal> provide convenience layers for
+ building DOM <literal>Document</literal>s using the configured
+ parsers.</para>
+
+ </section>
+
+ <section>
+ <title><literal>EntityResolver</literal></title>
+
+ <para>You can provide a custom
+ <literal>org.xml.sax.EntityResolver</literal> for the control
+ and test parsers via
+ <literal>XMLUnit.setControlEntityResolver</literal> and
+ <literal>XMLUnit.setTestEntityResolver</literal>.</para>
+ </section>
+
+ <section id="element-content-whitespace">
+ <title>Element Content Whitespace</title>
+
+ <para>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 <literal><![CDATA[<foo>]]></literal> and
+ <literal><![CDATA[<bar>]]></literal> in the following example
+ belongs into this category.</para>
+
+ <programlisting language="XML"><![CDATA[
+<foo>
+ <bar/></foo>
+]]></programlisting>
+
+ <para>Using <literal>XMLUnit.setIgnoreWhitespace</literal> it
+ is possible to make the test and control parser ignore this
+ kind of whitespace.</para>
+ </section>
+ </section>
+
+ <section id="input-choices">
+ <title>Providing Input to XMLUnit</title>
+
+ <para>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:</para>
+
+ <itemizedlist>
+
+ <listitem>A DOM <literal>Document</literal>.
+
+ <para>Here you have all control over the document's
+ creation. Such a <literal>Document</literal> could as well
+ be the result of an XSLT transformation via the
+ <literal>Transform</literal> class.</para>
+ </listitem>
+
+ <listitem>A <literal>String</literal>.
+
+ <para>Here a DOM <literal>Document</literal> is built from
+ the input <literal>String</literal> using the JAXP parser
+ specified for control or test documents - depending on
+ whether the input is a control or test piece of XML.</para>
+ </listitem>
+
+ <listitem>A <literal>Reader</literal>.
+
+ <para>Here a DOM <literal>Document</literal> is built from
+ the input <literal>Reader</literal> using the JAXP parser
+ specified for control or test documents - depending on
+ whether the input is a control or test piece of XML.</para>
+
+ <para>Note that using a <literal>Reader</literal> 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
+ <literal>Reader</literal> version to ensure encoding has
+ been dealt with properly.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
</section>
- <section id="Comparing"><title>Comparing XML documents</title>
+ <section id="Comparing"><title>Comparing Pieces of XML</title>
<section id="comparing-basics">
<title>The Difference Engine</title>
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
