Thread: SF.net SVN: xmlunit: [149] trunk/xmlunit/src/site/XMLUnit-Java.xml

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Revision: 149
          http://xmlunit.svn.sourceforge.net/xmlunit/?rev=149&view=rev
Author:   bodewig
Date:     2007-03-21 22:02:09 -0700 (Wed, 21 Mar 2007)

Log Message:
-----------
Add docbook version of user guide

Added Paths:
-----------
    trunk/xmlunit/src/site/XMLUnit-Java.xml

Added: trunk/xmlunit/src/site/XMLUnit-Java.xml
===================================================================

--- trunk/xmlunit/src/site/XMLUnit-Java.xml	                        (rev 0)
+++ trunk/xmlunit/src/site/XMLUnit-Java.xml	2007-03-22 05:02:09 UTC (rev 149)
@@ -0,0 +1,611 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1b1//EN" "http://docbook.org/xml/simple/1.1b1/sdocbook.dtd">
+
+<article>
+  <title>A Tour of XMLUnit
+    <inlinemediaobject><imageobject>
+        <imagedata fileref="xmlunit.png" width="331" depth="100"
+          valign="middle" format="PNG"/>
+      </imageobject></inlinemediaobject>
+  </title>
+  <articleinfo>
+    <authorgroup>
+      <author>
+        <firstname>Tim</firstname>
+        <surname>Bacon</surname>
+      </author>
+    </authorgroup>
+    <revhistory>
+      <revision>
+        <revnumber>1.0</revnumber>
+        <date>January 2003</date>
+        <author>
+          <firstname>Tim</firstname>
+          <surname>Bacon</surname>
+        </author>
+        <revremark>Documentation for XMLUnit Java 1.0</revremark>
+      </revision>
+    </revhistory>
+  </articleinfo>
+
+  <section><title>What is XMLUnit?</title>
+
+    <para>XMLUnit enables JUnit-style assertions to be made about the
+    content and structure of XML<footnote id="more on JUnit"><para>For
+    more information on JUnit see <ulink
+    url="http://www.junit.org">http://www.junit.org</ulink></para></footnote>. It
+    is an open source project hosted at http://xmlunit.sourceforge.net
+    that grew out of a need to test a system that generated and
+    received custom XML messages. The problem that we faced was how to
+    verify that the system generated the correct message from a known
+    set of inputs. Obviously we could use a DTD or a schema to
+    validate the message output, but this approach wouldn't allow us
+    to distinguish between valid XML with correct content (e.g.
+    element <literal><![CDATA[<foo>bar</foo>]]></literal>) and valid
+    XML with incorrect content (e.g.  element
+    <literal><![CDATA[<foo>baz</foo>]]></literal>). What we really
+    wanted was an <literal>assertXMLEquals()</literal> method, so we
+    could compare the message that we expected the system to generate
+    and the message that the system actually generated. And that was
+    the beginning of XMLUnit.</para>
+  </section>
+  <section><title>Quick tour</title>
+
+    <para>XMLUnit provides a single JUnit extension class,
+    <literal>XMLTestCase</literal>, and a set of supporting classes
+    that allow assertions to be made about:</para>
+
+    <itemizedlist>
+      <listitem>The differences between two pieces of XML (via
+      <literal>Diff</literal> and <literal>DetailedDiff</literal>
+      classes)</listitem>
+
+      <listitem>The validity of a piece of XML (via
+      <literal>Validator</literal> class)</listitem>
+
+      <listitem> The outcome of transforming a piece of XML using XSLT
+      (via <literal>Transform</literal> class)</listitem>
+
+      <listitem>The evaluation of an XPath expression on a piece of
+      XML (via <literal>SimpleXpathEngine</literal> class)</listitem>
+
+      <listitem>Individual nodes in a piece of XML that are exposed by
+      DOM Traversal (via <literal>NodeTest</literal> class)</listitem>
+    </itemizedlist>
+
+    <para>XMLUnit can also treat HTML content, even badly-formed HTML,
+    as valid XML to allow these assertions to be made about web pages
+    (via the <literal>HTMLDocumentBuilder</literal> class).</para>
+  </section>
+
+  <section><title>Glossary</title>
+
+    <para>As with many projects some words in XMLUnit have particular
+    meanings so here is a quick overview. A <emphasis>piece</emphasis>
+    of XML is a DOM Document, a String containing marked-up content,
+    or a Source or Reader that allows access to marked-up content
+    within some resource. XMLUnit compares the expected
+    <emphasis>control</emphasis> XML to some actual
+    <emphasis>test</emphasis> XML. The comparison can reveal that two
+    pieces of XML are <emphasis>identical</emphasis>,
+    <emphasis>similar</emphasis> or
+    <emphasis>different</emphasis>. The unit of measurement used by
+    the comparison is a <emphasis>difference</emphasis>, and
+    differences can be either <emphasis>recoverable</emphasis> or
+    <emphasis>unrecoverable</emphasis>. Two pieces of XML are
+    <emphasis>identical</emphasis> if there are <emphasis>no
+    differences</emphasis> between them, <emphasis>similar</emphasis>
+    if there are <emphasis>only recoverable differences</emphasis>
+    between them, and <emphasis>different</emphasis> if there are
+    <emphasis>any unrecoverable differences</emphasis> between
+    them.</para>
+  </section>
+
+  <section><title>Configuring XMLUnit</title>
+
+    <para>There are many Java XML parsers available, and XMLUnit
+    should work with any JAXP compliant parser library, such as Xerces
+    from the Apache Jakarta project. To use the XSL and XPath features
+    of XMLUnit a Trax compliant transformation engine is required,
+    such as Xalan, from the Apache Jakarta project. To configure
+    XMLUnit to use your parser and transformation engine set three
+    System properties before any tests are run, e.g.</para>
+
+    <example><title>Configuring JAXP via System Properties</title>
+      <programlisting language="Java"><![CDATA[
+System.setProperty("javax.xml.parsers.DocumentBuilderFactory",
+    "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl");
+System.setProperty("javax.xml.parsers.SAXParserFactory",
+    "org.apache.xerces.jaxp.SAXParserFactoryImpl");
+System.setProperty("javax.xml.transform.TransformerFactory",
+    "org.apache.xalan.processor.TransformerFactoryImpl");
+]]></programlisting>
+    </example>
+
+    <para>Alternatively there are static methods on the XMLUnit class
+    that can be called directly. The advantage of this approach is
+    that you can specify a different parser class for control and test
+    XML and change the current parser class at any time in your tests,
+    should you need to make assertions about the compatibility of
+    different parsers.</para>
+
+<example><title>Configuring JAXP via XMLUnit class</title>
+      <programlisting language="Java"><![CDATA[
+XMLUnit.setControlParser("org.apache.xerces.jaxp.DocumentBuilderFactoryImpl");
+XMLUnit.setTestParser("org.apache.xerces.jaxp.DocumentBuilderFactoryImpl");
+XMLUnit.setSAXParserFactory("org.apache.xerces.jaxp.SAXParserFactoryImpl");
+XMLUnit.setTransformerFactory("org.apache.xalan.processor.TransformerFactoryImpl");
+]]></programlisting>
+    </example>
+  </section>
+
+  <section><title>Writing XML comparison tests</title>
+
+    <para>Let's say we have two pieces of XML that we wish to compare
+    and assert that they are equal. We could write a simple test class
+    like this:</para>
+
+    <example><title>A simple comparison test</title>
+      <programlisting language="Java"><![CDATA[
+public class MyXMLTestCase extends XMLTestCase {
+    public MyXMLTestCase(String name) {
+        super(name);
+    }
+
+    public void testForEquality() throws Exception {
+        String myControlXML = "<msg><uuid>0x00435A8C</uuid></msg>";
+        String myTestXML = "<msg><localId>2376</localId></msg>";
+        assertXMLEqual("Comparing test xml to control xml",
+        myControlXML, myTestXML);
+    }
+}]]></programlisting></example>
+
+    <para>The <literal>assertXMLEqual</literal> test will pass if the
+    control and test XML are either similar or identical. Obviously in
+    this case the pieces of XML are different and the test will
+    fail. The failure message indicates both what the difference is
+    and the Xpath locations of the nodes that were being
+    compared:</para>
+
+    <programlisting><![CDATA[
+Comparing test xml to control xml
+[different] Expected element tag name 'uuid' but was 'localId' - comparing <uuid...> at /msg[1]/uuid[1] to <localId...> at /msg[1]/localId[1]
+]]></programlisting>
+
+    <para>When comparing pieces of XML, the
+    <literal>XMLTestCase</literal> actually creates an instance of the
+    <literal>Diff</literal> class. The <literal>Diff</literal> class
+    stores the result of an XML comparison and makes it available
+    through the methods <literal>similar()</literal> and
+    <literal>identical()</literal>. The
+    <literal>assertXMLEquals()</literal> method tests the value of
+    <literal>Diff.similar()</literal> and the
+    <literal>assertXMLIdentical()</literal> method tests the value of
+    <literal>Diff.identical()</literal>.</para>
+
+    <para>It is easy to create a <literal>Diff</literal> instance
+    directly without using the <literal>XMLTestCase</literal> class as
+    below:</para>
+
+    <example><title>Creating a <literal>Diff</literal>
+        instance</title>
+      <programlisting language="Java"><![CDATA[
+public void testXMLIdentical()throws Exception {
+    String myControlXML =
+        "<struct><int>3</int><boolean>false</boolean></struct>";
+    String myTestXML =
+        "<struct><boolean>false</boolean><int>3</int></struct>";
+    Diff myDiff = new Diff(myControlXML, myTestXML);
+    assertTrue("XML similar " + myDiff.toString(),
+    myDiff.similar());
+    assertTrue("XML identical " + myDiff.toString(),
+    myDiff.identical());
+}]]></programlisting></example>
+
+    <para>This test fails as two pieces of XML are similar but not
+    identical if their nodes occur in a different sequence. The
+    failure message reported by JUnit from the call to
+    <literal>myDiff.toString()</literal> looks like this:</para>
+
+    <programlisting><![CDATA[
+[not identical] Expected sequence of child nodes '0' but was '1' - comparing <int...> at /struct[1]/int[1] to <int...> at /struct[1]/int[1]
+]]></programlisting>
+
+    <para>For efficiency reasons a <literal>Diff</literal> stops the
+    comparison process as soon as the first difference is found. To
+    get all the differences between two pieces of XML an instance of
+    the <literal>DetailedDiff</literal> class, a subclass of
+    <literal>Diff</literal>, is required. Note that a
+    <literal>DetailedDiff</literal> is constructed using an existing
+    <literal>Diff</literal> instance.</para>
+
+    <para>Consider this test that uses a DetailedDiff:</para>
+
+    <example><title>Using <literal>DetailedDiff</literal></title>
+      <programlisting language="Java"><![CDATA[
+public void testAllDifferences() throws Exception {
+    String myControlXML = "<news><item id=\"1\">War</item>"
+        + "<item id=\"2\">Plague</item>"
+        + "<item id=\"3\">Famine</item></news>";
+    String myTestXML = "<news><item id=\"1\">Peace</item>"
+        + "<item id=\"2\">Health</item>"
+        + "<item id=\"3\">Plenty</item></news>";
+    DetailedDiff myDiff = new DetailedDiff(new Diff(myControlXML, myTestXML));
+    List allDifferences = myDiff.getAllDifferences();
+    assertEquals(myDiff.toString(), 2, allDifferences.size());
+}]]></programlisting></example>
+
+    <para>This test fails with the message below as each of the 3 news
+    items differs between the control and test XML:</para>
+
+    <programlisting><![CDATA[
+[different] Expected text value 'War' but was 'Peace' - comparing <item...>War</item> at /news[1]/item[1]/text()[1] to <item...>Peace</item> at /news[1]/item[1]/text()[1]
+[different] Expected text value 'Plague' but was 'Health' - comparing <item...>Plague</item> at /news[1]/item[2]/text()[1] to <item...>Health</item> at /news[1]/item[2]/text()[1]
+[different] Expected text value 'Famine' but was 'Plenty' - comparing <item...>Famine</item> at /news[1]/item[3]/text()[1] to <item...>Plenty</item> at /news[1]/item[3]/text()[1]
+expected <2> but was <3>
+]]></programlisting>
+
+    <para>The List returned from the
+    <literal>getAllDifferences()</literal> method contains
+    <literal>Difference</literal> instances. These instances describe
+    both the type<footnote id="DifferenceConstants"><para>A full set
+    of prototype <literal>Difference</literal> instances - one for
+    each type of difference - is defined using final static fields in
+    the <literal>DifferenceConstants</literal>
+    class.</para></footnote> of difference found between a control
+    node and test node and the <literal>NodeDetail</literal> of those
+    nodes (including the XPath location of each
+    node). <literal>Difference</literal> instances are passed at
+    runtime in notification events to a registered
+    <literal>DifferenceListener</literal>, an interface whose default
+    implementation is provided by the <literal>Diff</literal>
+    class.</para>
+
+    <para>However it is possible to override this default behaviour by
+    implementing the interface in your own class.  The
+    <literal>IgnoreTextAndAttributeValuesDifferenceListener</literal>
+    class is an example of how to implement a custom
+    <literal>DifferenceListener</literal>. It allows an XML comparison
+    to be made that ignores differences in the values of text and
+    attribute nodes, for example when comparing a skeleton or outline
+    piece of XML to some generated XML.</para>
+
+    <para>The following test illustrates the use of a custom
+    <literal>DifferenceListener</literal>:</para>
+
+    <example><title>Using a custom
+        <literal>DifferenceListener</literal></title>
+      <programlisting language="Java"><![CDATA[
+public void testCompareToSkeletonXML() throws Exception {
+    String myControlXML = "<location><street-address>22 any street</street-address><postcode>XY00 99Z</postcode></location>";
+    String myTestXML = "<location><street-address>20 east cheap</street-address><postcode>EC3M 1EB</postcode></location>";
+    DifferenceListener myDifferenceListener = new IgnoreTextAndAttributeValuesDifferenceListener();
+    Diff myDiff = new Diff(myControlXML, myTestXML);
+    myDiff.overrideDifferenceListener(myDifferenceListener);
+    assertTrue("test XML matches control skeleton XML",
+    myDiff.similar());
+}]]></programlisting></example>
+
+    <para>The <literal>DifferenceEngine</literal> class generates the
+    events that are passed to a <literal>DifferenceListener</literal>
+    implementation as two pieces of XML are compared. Using recursion
+    it navigates through the nodes in the control XML DOM, and
+    determines which node in the test XML DOM qualifies for comparison
+    to the current control node. The qualifying test node will match
+    the control node's node type, as well as the node name and
+    namespace (if defined for the control node).</para>
+
+    <para>However when the control node is an
+    <literal>Element</literal>, it is less straightforward to
+    determine which test <literal>Element</literal> qualifies for
+    comparison as the parent node may contain repeated child
+    <literal>Element</literal>s with the same name and namespace. So
+    for <literal>Element</literal> nodes, an instance of the
+    <literal>ElementQualifier</literal> interface is used determine
+    whether a given test <literal>Element</literal> node qualifies for
+    comparison with a control <literal>Element</literal> node. This
+    separates the decision about whether two
+    <literal>Elements</literal> should be compared from the decision
+    about whether those two <literal>Elements</literal> are considered
+    similar. By default an <literal>ElementNameQualifier</literal>
+    class is used that compares the nth child
+    <literal><![CDATA[<abc>]]></literal> test element to the nth child
+    <literal><![CDATA[<abc>]]></literal> control element, i.e. the
+    sequence of the child elements in the test XML is
+    important. However this default behaviour can be overridden using
+    an <literal>ElementNameAndTextQualifier</literal> or
+    <literal>ElementNameAndAttributesQualifier</literal>.</para>
+
+    <para>The test below demonstrates the use of a custom
+    <literal>ElementQualifier</literal>:</para>
+
+    <example><title>Using a custom <literal>ElementQualifier</literal></title>
+      <programlisting language="Java"><![CDATA[
+public void testRepeatedChildElements() throws Exception {
+    String myControlXML = "<suite>"
+        + "<test status=\"pass\">FirstTestCase</test>"
+        + "<test status=\"pass\">SecondTestCase</test></suite>";
+    String myTestXML = "<suite>"
+        + "<test status=\"pass\">SecondTestCase</test>"
+        + "<test status=\"pass\">FirstTestCase</test></suite>";
+    assertXMLNotEqual("Repeated child elements in different sequence order are not equal by default",
+                      myControlXML, myTestXML);
+    Diff myDiff = new Diff(myControlXML, myTestXML);
+    myDiff.overrideElementQualifier(new ElementNameAndTextQualifier());
+    assertXMLEqual("But they are equal when an ElementQualifier controls which test element is compared with each control element",
+                    myDiff, true);
+}]]></programlisting></example>
+
+  </section>
+
+  <section><title>Comparing XML Transformations</title>
+
+    <para>XMLUnit can test XSL transformations at a high level using
+    the <literal>Transform</literal> class that wraps an
+    <literal>javax.xml.transform.Transformer</literal>
+    instance. Knowing the input XML, input stylesheet and expected
+    output XML we can assert that the output of the transformation
+    matches the expected output as follows:</para>
+
+    <example><title>Testing the Result of a Transformation</title>
+      <programlisting language="Java"><![CDATA[
+public void testXSLTransformation() throws Exception {
+    String myInputXML = "...";
+    File myStylesheetFile = new File("...");
+    Transform myTransform = new Transform(myInputXML, myStylesheetFile);
+    String myExpectedOutputXML = "...";
+    Diff myDiff = new Diff(myExpectedOutputXML, myTransform);
+    assertTrue("XSL transformation worked as expected", myDiff.similar());
+}]]></programlisting></example>
+
+    <para>The <literal>getResultString()</literal> and
+    <literal>getResultDocument()</literal> methods of the
+    <literal>Transform</literal> class can be used to access the
+    result of the XSL transformation programmatically if required, for
+    example as below:</para>
+
+    <example><title>Using <literal>Transform</literal> programmatically</title>
+      <programlisting language="Java"><![CDATA[
+public void testAnotherXSLTransformation() throws Exception {
+    File myInputXMLFile = new File("...");
+    File myStylesheetFile = new File("...");
+    Transform myTransform = new Transform(
+        new StreamSource(myInputXMLFile),
+        new StreamSource(myStylesheetFile));
+    Document myExpectedOutputXML =
+       XMLUnit.buildDocument(XMLUnit.getControlParser(),
+                             new FileReader("..."));
+    Diff myDiff = new Diff(myExpectedOutputXML,
+    myTransform.getResultDocument());
+    assertTrue("XSL transformation worked as expected", myDiff.similar());
+}]]></programlisting></example>
+
+  </section>
+
+  <section><title>Validation Tests</title>
+
+    <para>XML parsers that validate a piece of XML against a DTD are
+    common, however they rely on a DTD reference being present in the
+    XML, and they can only validate against a single DTD. When writing
+    a system that exchanges XML messages with third parties there are
+    times when you would like to validate the XML against a DTD that
+    is not available to the recipient of the message and so cannot be
+    referenced in the message itself. XMLUnit provides a
+    <literal>Validator</literal> class for this purpose.</para>
+
+    <example><title>Validating Against a DTD</title>
+      <programlisting language="Java"><![CDATA[
+public void testValidation() throws Exception {
+    XMLUnit.getTestDocumentBuilderFactory().setValidating(true);
+    // As the document is parsed it is validated against its referenced DTD
+    Document myTestDocument = XMLUnit.buildTestDocument("...");
+    String mySystemId = "...";
+    String myDTDUrl = new File("...").toURL().toExternalForm();
+    Validator myValidator = new Validator(myTestDocument, mySystemId,
+                                          myDTDUrl);
+    assertTrue("test document validates against unreferenced DTD",
+               myValidator.isValid());
+}]]></programlisting></example>
+
+  </section>
+
+  <section><title>Xpath Tests</title>
+
+    <para>One of the strengths of XML is the ability to
+    programmatically extract specific parts of a document using XPath
+    expressions. The <literal>XMLTestCase</literal> class offers a
+    number of XPath related assertion methods, as demonstrated in this
+    test:</para>
+
+    <example><title>Using Xpath Tests</title>
+      <programlisting language="Java"><![CDATA[
+public void testXPaths() throws Exception {
+    String mySolarSystemXML = "<solar-system>"
+        + "<planet name='Earth' position='3' supportsLife='yes'/>"
+        + "<planet name='Venus' position='4'/></solar-system>";
+    assertXpathExists("//planet[@name='Earth']", mySolarSystemXML);
+    assertNotXpathExists("//star[@name='alpha centauri']",
+                         mySolarSystemXML);
+    assertXpathsEqual("//planet[@name='Earth']",
+                      "//planet[@position='3']", mySolarSystemXML);
+    assertXpathsNotEqual("//planet[@name='Venus']",
+                         "//planet[@supportsLife='yes']",
+                         mySolarSystemXML);
+}]]></programlisting></example>
+
+    <para>When an XPath expression is evaluated against a piece of XML
+    a <literal>NodeList</literal> is created that contains the
+    matching <literal>Node</literal>s. The methods in the previous
+    test <literal>assertXPathExists</literal>,
+    <literal>assertNotXPathExists</literal>,
+    <literal>assertXPathsEqual</literal>, and
+    <literal>assertXPathsNotEqual</literal> use these
+    <literal>NodeList</literal>s. However, the contents of a
+    <literal>NodeList</literal> can be flattened (or
+    <literal>String</literal>-ified) to a single value, and XMLUnit
+    also allows assertions to be made about this single value, as in
+    this test<footnote id="SimpleXpathEngine note"><para>Each of the
+    <literal>assertXpath...()</literal> methods uses the
+    <literal>SimpleXpathEngine</literal> class to evaluate an Xpath
+    expression.</para></footnote>:</para>
+
+    <example><title>Testing Xpath Values</title>
+      <programlisting language="Java"><![CDATA[
+public void testXPathValues() throws Exception {
+    String myJavaFlavours = "<java-flavours>"
+        + "<jvm current='some platforms'>1.1.x</jvm>"
+        + "<jvm current='no'>1.2.x</jvm>"
+        + "<jvm current='yes'>1.3.x</jvm>"
+        + "<jvm current='yes' latest='yes'>1.4.x</jvm></javaflavours>";
+    assertXpathEvaluatesTo("2", "count(//jvm[@current='yes'])",
+                           myJavaFlavours);
+    assertXpathValuesEqual("//jvm[4]/@latest", "//jvm[4]/@current",
+                           myJavaFlavours);
+    assertXpathValuesNotEqual("//jvm[2]/@current",
+                              "//jvm[3]/@current", myJavaFlavours);
+}]]></programlisting></example>
+
+    <para>Xpaths are especially useful where a document is made up
+    largely of known, unchanging content with only a small amount of
+    changing content created by the system. One of the main areas
+    where constant "boilerplate" markup is combined with system
+    generated markup is of course in web applications. The power of
+    XPath expressions can make testing web page output quite trivial,
+    and XMLUnit supplies a means of converting even very badly formed
+    HTML into XML to aid this approach to testing.</para>
+
+    <para>The <literal>HTMLDocumentBuilder</literal> class uses the
+    Swing HTML parser to convert marked-up content to Sax events. The
+    <literal>TolerantSaxDocumentBuilder</literal> class handles the
+    Sax events to build up a DOM document in a tolerant fashion
+    i.e. without mandating that opened elements are closed. (In a
+    purely XML world this class would have no purpose as there are
+    plenty of Sax event handlers that can build DOM documents from
+    well formed content). The test below illustrates how the use of
+    these classes:</para>
+
+    <example><title>Working with non well-formed HTML</title>
+      <programlisting language="Java"><![CDATA[
+public void testXpathsInHTML() throws Exception {
+    String someBadlyFormedHTML = "<html><title>Ugh</title>"
+        + "<body><h1>Heading<ul>"
+        + "<li id='1'>Item One<li id='2'>Item Two";
+    TolerantSaxDocumentBuilder tolerantSaxDocumentBuilder =
+        new TolerantSaxDocumentBuilder(XMLUnit.getTestParser());
+    HTMLDocumentBuilder htmlDocumentBuilder =
+        new HTMLDocumentBuilder(tolerantSaxDocumentBuilder);
+    Document wellFormedDocument =
+        htmlDocumentBuilder.parse(someBadlyFormedHTML);
+    assertXpathEvaluatesTo("Item One", "/html/body//li[@id='1']",
+                           wellFormedDocument);
+}]]></programlisting></example>
+
+    <para>One of the key points about using Xpaths with HTML content
+    is that extracting values in tests requires the values to be
+    identifiable. (This is just another way of saying that testing
+    HTML is easier when it is written to be testable.) In the previous
+    example id attributes were used to identify the list item values
+    that needed to be testable, however class attributes or span and
+    div tags can also be used to identify specific content for
+    testing.</para>
+
+  </section>
+
+  <section><title>Testing by Tree Walking</title>
+
+    <para>The DOM specification allows a <literal>Document</literal>
+    to optionally implement the <literal>DocumentTraversal</literal>
+    interface. This interface allows an application to iterate over
+    the <literal>Node</literal>s contained in a
+    <literal>Document</literal>, or to "walk the DOM tree". The
+    XMLUnit <literal>NodeTest</literal> class and
+    <literal>NodeTester</literal> interface make use of
+    <literal>DocumentTraversal</literal> to expose individual
+    <literal>Node</literal>s in tests: the former handles the
+    mechanics of iteration, and the latter allows custom test
+    strategies to be implemented. A sample test strategy is supplied
+    by the <literal>CountingNodeTester</literal> class that counts the
+    nodes presented to it and compares the actual count to an expected
+    count. The test below illustrates its use:</para>
+
+    <example><title>Using <literal>CountingNodeTester</literal></title>
+      <programlisting language="Java"><![CDATA[
+public void testCountingNodeTester() throws Exception {
+    String testXML = "<fibonacci><val>1</val><val>2</val><val>3</val>"
+        + "<val>5</val><val>9</val></fibonacci>";
+    CountingNodeTester countingNodeTester = new CountingNodeTester(4);
+    assertNodeTestPasses(testXML, countingNodeTester, Node.TEXT_NODE);
+}]]></programlisting></example>
+
+    <para>This test fails as there are 5 text nodes, and JUnit
+    supplies the following message:</para>
+
+    <programlisting>
+Expected node test to pass, but it failed! Counted 5 node(s) but
+expected 4
+    </programlisting>
+
+    <para>Note that if your DOM implementation does not support the
+    <literal>DocumentTraversal</literal> interface then XMLUnit will
+    throw an <literal>IllegalArgumentException</literal> informing you
+    that you cannot use the <literal>NodeTest</literal> or
+    <literal>NodeTester</literal> classes. Unfortunately even if your
+    DOM implementation does support
+    <literal>DocumentTraversal</literal>, attributes are not exposed
+    by iteration: however they can be examined from the
+    <literal>Element</literal> node that contains them.</para>
+
+    <para>While the previous test could have been easily performed
+    using XPath, there are times when <literal>Node</literal>
+    iteration is more powerful. In general, this is true when there
+    are programmatic relationships between nodes that can be more
+    easily tested iteratively. The following test uses a custom
+    <literal>NodeTester</literal> class to illustrate the
+    potential:</para>
+
+    <example><title>Using a Custom <literal>NodeTester</literal></title>
+      <programlisting language="Java"><![CDATA[
+public void testCustomNodeTester() throws Exception {
+    String testXML = "<fibonacci><val>1</val><val>2</val><val>3</val>"
+        + "<val>5</val><val>9</val></fibonacci>";
+    NodeTest nodeTest = new NodeTest(testXML);
+    assertNodeTestPasses(nodeTest, new FibonacciNodeTester(),
+                         new short[] {Node.TEXT_NODE,
+                                      Node.ELEMENT_NODE},
+                         true);
+}
+
+private class FibonacciNodeTester extends AbstractNodeTester {
+    private int nextVal = 1, lastVal = 1, priorVal = 0;
+
+    public void testText(Text text) throws NodeTestException {
+        int val = Integer.parseInt(text.getData());
+        if (nextVal != val) {
+            throw new NodeTestException("Incorrect value", text);
+        }
+        nextVal = val + lastVal;
+        priorVal = lastVal;
+        lastVal = val;
+    }
+
+    public void testElement(Element element) throws NodeTestException {
+        String name = element.getLocalName();
+        if ("fibonacci".equals(name) || "val".equals(name)) {
+            return;
+        }
+        throw new NodeTestException("Unexpected element", element);
+    }
+
+    public void noMoreNodes(NodeTest nodeTest) throws NodeTestException {
+    }
+}]]></programlisting></example>
+
+    <para>The test fails because the XML contains the wrong value for
+    the last number in the sequence:</para>
+
+    <programlisting>
+Expected node test to pass, but it failed! Incorrect value [#text: 9]
+    </programlisting>
+
+  </section>
+</article>


Property changes on: trunk/xmlunit/src/site/XMLUnit-Java.xml
___________________________________________________________________
Name: svn:eol-style
   + native


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




Thread: SF.net SVN: xmlunit: [149] trunk/xmlunit/src/site/XMLUnit-Java.xml

XMLUnit provides assertions that help testing code that produces XML.

xmlunit-commits