Document yet another classloading quirk within <junit>, PR: 24646

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@276350 13f79535-47bb-0310-9956-ffa450edef68

docs/faq.html

@@ -347,6 +347,12 @@
         The program I run via <java> throws an exception but I
         can't seem to get the full stack trace.
       
+      </a></li>
+                <li><a href="#junit-no-runtime-xml">
+  
+        Using format="xml", &lt;junit&gt; fails with a
+        <code>NoClassDefFoundError</code> if forked.
+      
       </a></li>
             </ul>
     
@@ -1622,6 +1628,31 @@ mv /tmp/foo $ANT_HOME/bin/antRun
                         <p>As a workaround, run your &lt;java&gt; task with
         <code>fork="true"</code> and Ant will display the full
         trace.</p>
+                    <p class="faq">
+      <a name="junit-no-runtime-xml"></a>
+      
+        Using format="xml", &lt;junit&gt; fails with a
+        <code>NoClassDefFoundError</code> if forked.
+      
+    </p>
+                  <p>The XML formatter needs the <a href="http://www.w3.org/DOM/">DOM classes</a> to work.  If you
+        are using JDK 1.4 or later they are included with your Java
+        Runtime and this problem won't occur.  If you are running JDK
+        1.3 or earlier, the DOM classes have to be on your
+        &lt;junit&gt; task's &lt;classpath&gt;.</p>
+                        <p>Prior to Ant 1.6.0 Ant would include the DOM classes from
+        the XML parser that is used by Ant itself if you set the
+        includeAntRuntime attribute to true (the default).  With Ant
+        1.6.0 this has been changed as this behavior made it
+        impossible to use a different XML parser in your tests.</p>
+                        <p>This means that you have to take care of the DOM classes
+        explicitly starting with Ant 1.6.0.  If you don't need to set
+        up a different XML parser for your tests, the easiest solution
+        is to add</p>
+                        <pre class="code">
+&lt;pathelement path=&quot;${ant.home}/lib/xml-apis.jar:${ant.home}/lib/xercesImpl.jar&quot;/&gt;
+</pre>
+                        <p>to your task's &lt;classpath&gt;.</p>
                     </div>
   </div>
 

docs/manual/OptionalTasks/junit.html

@@ -132,7 +132,11 @@ elements</a>).</p>
   <tr>
     <td valign="top">includeantruntime</td>
     <td valign="top">Implicitly add the Ant classes required to run
-      the tests and JUnit to the classpath in forked mode.</td>
+      the tests and JUnit to the classpath in forked mode.
+      <b>Note:</b> Please read the <a
+      href="../../faq.html#junit-no-runtime-xml">Ant FAQ</a> if you
+      want to set this to <code>false</code> and use the XML formatter
+      at the same time.</td>
     <td align="center" valign="top">No; default is <code>true</code>.</td>
   </tr>
   <tr>
@@ -291,6 +295,12 @@ can be specified.</p>
 that your tests have written as some characters are illegal in XML
 documents and will be dropped.</p>
 
+<p><b>Note:</b> Please read the <a
+href="../../faq.html#junit-no-runtime-xml">Ant FAQ</a> if you want to
+set the fork attribute to <code>true</code>, the includeAntRuntime
+attribute to <code>false</code> and use the XML formatter at the same
+time.</p>
+
 <table border="1" cellpadding="2" cellspacing="0">
 <tr>
   <td width="12%" valign="top"><b>Attribute</b></td>

xdocs/faq.xml

@@ -1435,6 +1435,40 @@ mv /tmp/foo $ANT_HOME/bin/antRun
         trace.</p>
       </answer>
     </faq>
+
+    <faq id="junit-no-runtime-xml">
+      <question>
+        Using format=&quot;xml&quot;, &lt;junit&gt; fails with a
+        <code>NoClassDefFoundError</code> if forked.
+      </question>
+      <answer>
+
+        <p>The XML formatter needs the <a
+        href="http://www.w3.org/DOM/">DOM classes</a> to work.  If you
+        are using JDK 1.4 or later they are included with your Java
+        Runtime and this problem won't occur.  If you are running JDK
+        1.3 or earlier, the DOM classes have to be on your
+        &lt;junit&gt; task's &lt;classpath&gt;.</p>
+
+        <p>Prior to Ant 1.6.0 Ant would include the DOM classes from
+        the XML parser that is used by Ant itself if you set the
+        includeAntRuntime attribute to true (the default).  With Ant
+        1.6.0 this has been changed as this behavior made it
+        impossible to use a different XML parser in your tests.</p>
+
+        <p>This means that you have to take care of the DOM classes
+        explicitly starting with Ant 1.6.0.  If you don't need to set
+        up a different XML parser for your tests, the easiest solution
+        is to add</p>
+
+        <source><![CDATA[
+<pathelement path="${ant.home}/lib/xml-apis.jar:${ant.home}/lib/xercesImpl.jar"/>
+]]></source>
+
+        <p>to your task's &lt;classpath&gt;.</p>
+
+      </answer>
+    </faq>
   </faqsection>
 
 </document>