Add Stefan's note wrt needing junit.jar and <junit> class files

in the same classpath. (And the usual compulsive clean-up :)
PR:
Obtained from:
Submitted by:
Reviewed by:


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

docs/manual/OptionalTasks/junit.html

@@ -10,16 +10,39 @@
 <p>This task runs tests from the JUnit testing framework. The latest
 version of the framework can be found at
 <a href="http://www.junit.org">http://www.junit.org</a>.
-This task has been tested with JUnit 3.0 up to JUnit 3.7, it won't
+This task has been tested with JUnit 3.0 up to JUnit 3.7; it won't
 work with versions prior to JUnit 3.0.</p>
 <p><strong>Note:</strong> This task depends on external libraries not included
 in the Ant distribution.  See <a href="../install.html#librarydependencies">
 Library Dependencies</a> for more information.
 </p>
+<p>
+<strong>Note</strong>:
+You must have <code>junit.jar</code> and the class files for the
+<code>&lt;junit&gt;</code> task in the same classpath.
+You can do one of:
+<ol>
+<li>
+Put both <code>junit.jar</code> and the optional tasks jar file in
+<code>ANT_HOME/lib</code>.
+</li>
+<li>
+Do not put either in <code>ANT_HOME/lib</code>, and instead
+include their locations in your <code>CLASSPATH</code> environment variable.
+</li>
+<li>
+Do neither of the above, and instead, specify their locations using
+a <code>&lt;classpath&gt;</code> element in the build file.
+
+See <a href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6606">the
+bugs database</a> for details.
+</ol>
+</p>
+
 
 <p>Tests are defined by nested <code>test</code> or
-<code>batchtest</code> tags, see <a href="#nested">nested
-elements</a>.</p>
+<code>batchtest</code> tags (see <a href="#nested">nested
+elements</a>).</p>
 
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
@@ -30,97 +53,120 @@ elements</a>.</p>
 </tr>
   <tr>
     <td valign="top">printsummary</td>
-    <td valign="top">Print one line statistics for each testcase. Can
-      take the values &quot;on&quot;, &quot;off&quot; and
-      &quot;withOutAndErr&quot; - &quot;withOutAndErr&quot; is the same
-      as &quot;on&quot; but also includes the output of the test
-      as written to System.out and System.err.</td>
-    <td align="center" valign="top">No, default is "off"</td>
+    <td valign="top">Print one-line statistics for each testcase. Can
+      take the values <code>on</code>,
+      <code>off</code>, and
+      <code>withOutAndErr</code>.
+      <code>withOutAndErr</code> is the same
+      as <code>on</code> but also includes the output of the test
+      as written to <code>System.out</code> and <code>System.err</code>.</td>
+    <td align="center" valign="top">No; default is <code>off</code>.</td>
   </tr>
   <tr>
     <td valign="top">fork</td>
     <td valign="top">Run the tests in a separate VM.</td>
-    <td align="center" valign="top">No, default is "off"</td>
+    <td align="center" valign="top">No; default is <code>off</code>.</td>
   </tr>
   <tr>
     <td valign="top">haltonerror</td>
     <td valign="top">Stop the build process if an error occurs during the test
        run.</td>
-    <td align="center" valign="top">No, default is "off"</td>
+    <td align="center" valign="top">No; default is <code>off</code>.</td>
   </tr>
 <tr>
-    <td valign="top">errorProperty</td>
+    <td valign="top">errorproperty</td>
     <td valign="top">The name of a property to set in the event of an error.</td>
-    <td align="center" valign="top">No.</td>
+    <td align="center" valign="top">No</td>
 </tr>
   <tr>
     <td valign="top">haltonfailure</td>
     <td valign="top">Stop the build process if a test fails (errors are
       considered failures as well).</td>
-    <td align="center" valign="top">No, default is "off"</td>
+    <td align="center" valign="top">No; default is <code>off</code>.</td>
   </tr>
 <tr>
-    <td valign="top">failureProperty</td>
+    <td valign="top">failureproperty</td>
     <td valign="top">The name of a property to set in the event of a failure
       (errors are considered failures as well).</td>
     <td align="center" valign="top">No.</td>
 </tr>
   <tr>
     <td valign="top">filtertrace</td>
-    <td valign="top">Filter out junit and ant stack frames from error and failure stack traces.</td>
-    <td align="center" valign="top">No, default is "on."</td>
+    <td valign="top">Filter out Junit and Ant stack frames from error and failure stack traces.</td>
+    <td align="center" valign="top">No; default is <code>on</code>.</td>
   </tr>
   <tr>
     <td valign="top">timeout</td>
-    <td valign="top">Cancel the individual tests if the don't finish
-      in the given time (measured in milliseconds).  Ignored if fork is
-      disabled.</td>
+    <td valign="top">Cancel the individual tests if they don&apos;t finish
+      in the given time (measured in milliseconds).  Ignored if
+      <code>fork</code> is disabled.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">maxmemory</td>
-    <td valign="top">Max amount of memory to allocate to the forked VM
-      (ignored if fork is disabled)</td>
+    <td valign="top">Maximum amount of memory to allocate to the forked VM.
+      Ignored if <code>fork</code> is disabled.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">jvm</td>
-    <td valign="top">the command used to invoke the Java Virtual Machine,
-      default is 'java'.  The command is resolved by java.lang.Runtime.exec().
-      Ignored if fork is disabled.</td>
-    <td align="center" valign="top">No, default &quot;java&quot;</td>
+    <td valign="top">The command used to invoke the Java Virtual Machine,
+      default is 'java'.  The command is resolved by
+      <code>java.lang.Runtime.exec()</code>.
+      Ignored if <code>fork</code> is disabled.</td>
+    <td align="center" valign="top">No; default is <code>java</code>.</td>
   </tr>
   <tr>
     <td valign="top">dir</td>
-    <td valign="top">The directory to invoke the VM in. (ignored if
-      fork is disabled)</td>
+    <td valign="top">The directory in which to invoke the VM. Ignored if
+      <code>fork</code> is disabled.</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">newenvironment</td>
-    <td valign="top">Do not propagate old environment when new
-      environment variables are specified.  Ignored if fork is
+    <td valign="top">Do not propagate the old environment when new
+      environment variables are specified. Ignored if <code>fork</code> is
       disabled.</td>
-    <td align="center" valign="top">No, default is &quot;false&quot;.</td>
+    <td align="center" valign="top">No; default is <code>false</code>.</td>
   </tr>
   <tr>
     <td valign="top">includeantruntime</td>
-    <td valign="top">implicitly add the Ant classes required to run
+    <td valign="top">Implicitly add the Ant classes required to run
       the tests and JUnit to the classpath in forked mode.</td>
-    <td align="center" valign="top">No, default is &quot;true&quot;.</td>
+    <td align="center" valign="top">No; default is <code>true</code>.</td>
   </tr>
 </table>
 
+<p>By using the <code>errorproperty</code> and <code>failureproperty</code>
+attributes, it is possible to
+perform setup work (such as starting an external server), execute the test,
+clean up, and still fail the build in the event of a failure.</p>
+
+<p>The <code>filtertrace</code> attribute condenses error and failure
+stack traces before reporting them.
+It works with both the plain and XML formatters.  It filters out any lines
+that begin with the following string patterns:<pre>
+   "junit.framework.TestCase"
+   "junit.framework.TestResult"
+   "junit.framework.TestSuite"
+   "junit.framework.Assert."
+   "junit.swingui.TestRunner"
+   "junit.awtui.TestRunner"
+   "junit.textui.TestRunner"
+   "java.lang.reflect.Method.invoke("
+   "org.apache.tools.ant."</pre></p>
+
 <h3><a name="nested">Nested Elements</a></h3>
 
-<p><code>junit</code> supports a nested <code>&lt;classpath&gt;</code>
-element, that represents a <a href="../using.html#path">PATH like
+<p>The <code>&lt;junit&gt;</code> task
+supports a nested <code>&lt;classpath&gt;</code>
+element that represents a <a href="../using.html#path">PATH like
 structure</a>.</p>
 
 <h4>jvmarg</h4>
 
-<p>If fork is enabled, additional parameters may be passed to the new
-VM via nested <code>&lt;jvmarg&gt;</code> attributes, for example:</p>
+<p>If <code>fork</code> is enabled, additional parameters may be passed to
+the new VM via nested <code>&lt;jvmarg&gt;</code> elements. For example:</p>
 
 <pre>
 &lt;junit fork=&quot;yes&quot;&gt;
@@ -132,13 +178,14 @@ VM via nested <code>&lt;jvmarg&gt;</code> attributes, for example:</p>
 <p>would run the test in a VM without JIT.</p>
 
 <p><code>&lt;jvmarg&gt;</code> allows all attributes described in <a
-href="../using.html#arg">Command line arguments</a>.</p>
+href="../using.html#arg">Command-line Arguments</a>.</p>
 
 <h4>sysproperty</h4>
 
 <p>Use nested <code>&lt;sysproperty&gt;</code> elements to specify system
 properties required by the class. These properties will be made available
-to the VM during the execution of the test (either ANT's VM or the forked VM).
+to the VM during the execution of the test (either ANT's VM or the forked VM,
+if <code>fork</code> is enabled).
 The attributes for this element are the same as for <a href="../CoreTasks/exec.html#env">environment variables</a>.</p>
 
 <pre>
@@ -155,24 +202,25 @@ available to the test.</p>
 <h4>env</h4>
 
 <p>It is possible to specify environment variables to pass to the
-forked VM via nested <code>&lt;env&gt;</code> elements. See the
-description in the section about
-<a href="../CoreTasks/exec.html#env">exec</a></p>
+forked VM via nested <code>&lt;env&gt;</code> elements. For a description
+of the <code>&lt;env&gt;</code> element's attributes, see the
+description in the <a href="../CoreTasks/exec.html#env">exec</a> task.</p>
 
-<p>Settings will be ignored if fork is disabled.</p>
+<p>Settings will be ignored if <code>fork</code> is disabled.</p>
 
 <h4>formatter</h4>
 
 <p>The results of the tests can be printed in different
-formats. Output will always be sent to a file unless you set the
-usefile attribute to false, the name of the file is determined by the
+formats. Output will always be sent to a file, unless you set the
+<code>usefile</code> attribute to <code>false</code>.
+The name of the file is determined by the
 name of the test and can be set by the <code>outfile</code> attribute
 of <code>&lt;test&gt;</code>.</p>
 
-<p>There are three predefined formatters, one prints the test results
-in XML format, the other emit plain text.  The formatter named
-&quot;brief&quot; will only print detailed information for testcases
-that failed, while &quot;plain&quot; gives a little statistics line
+<p>There are three predefined formatters - one prints the test results
+in XML format, the other emits plain text.  The formatter named
+<code>brief</code> will only print detailed information for testcases
+that failed, while <code>plain</code> gives a little statistics line
 for all test cases.  Custom formatters that need to implement
 <code>org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter</code>
 can be specified.</p>
@@ -186,7 +234,7 @@ can be specified.</p>
   <tr>
     <td valign="top">type</td>
     <td valign="top">Use a predefined formatter (either
-      &quot;xml&quot;, &quot;plain&quot; or &quot;brief&quot;).</td>
+      <code>xml</code>, <code>plain</code>, or <code>brief</code>).</td>
     <td align="center" rowspan="2">Exactly one of these.</td>
   </tr>
   <tr>
@@ -196,13 +244,13 @@ can be specified.</p>
   <tr>
     <td valign="top">extension</td>
     <td valign="top">Extension to append to the output filename.</td>
-    <td align="center">Yes, if classname has been used.</td>
+    <td align="center">Yes, if <code>classname</code> has been used.</td>
   </tr>
   <tr>
     <td valign="top">usefile</td>
     <td valign="top">Boolean that determines whether output should be
       sent to a file.</td>
-    <td align="center">No, default true.</td>
+    <td align="center">No; default is <code>true</code>.</td>
   </tr>
 </table>
 
@@ -218,7 +266,7 @@ can be specified.</p>
 </tr>
   <tr>
     <td valign="top">name</td>
-    <td valign="top">Name of the test class</td>
+    <td valign="top">Name of the test class.</td>
     <td align="center">Yes</td>
   </tr>
   <tr>
@@ -234,10 +282,10 @@ can be specified.</p>
     <td align="center" valign="top">No</td>
   </tr>
 <tr>
-    <td valign="top">errorProperty</td>
+    <td valign="top">errorproperty</td>
     <td valign="top">The name of a property to set in the event of an error.
-      Overrides value set in &lt;junit&gt;.</td>
-    <td align="center" valign="top">No.</td>
+      Overrides value set in <code>&lt;junit&gt;</code>.</td>
+    <td align="center" valign="top">No</td>
 </tr>
   <tr>
     <td valign="top">haltonfailure</td>
@@ -247,29 +295,31 @@ can be specified.</p>
     <td align="center" valign="top">No</td>
   </tr>
 <tr>
-    <td valign="top">failureProperty</td>
+    <td valign="top">failureproperty</td>
     <td valign="top">The name of a property to set in the event of a failure
-      (errors are considered failures as well). Overrides value set in &lt;junit&gt;.</td>
-    <td align="center" valign="top">No.</td>
+      (errors are considered failures as well). Overrides value set in
+      <code>&lt;junit&gt;</code>.</td>
+    <td align="center" valign="top">No</td>
 </tr>
   <tr>
     <td valign="top">filtertrace</td>
-    <td valign="top">Filter out junit and ant stack frames from error and failure stack
-    traces.  Overrides value set in &lt;junit&gt;</td>
-    <td align="center" valign="top">No, default is "on."</td>
+    <td valign="top">Filter out Junit and Ant stack frames from error and failure stack
+    traces.  Overrides value set in <code>&lt;junit&gt;</code>.</td>
+    <td align="center" valign="top">No; default is <code>on</code>.</td>
   </tr>
   <tr>
     <td valign="top">todir</td>
     <td valign="top">Directory to write the reports to.</td>
-    <td align="center" valign="top">No, default is current directory.</td>
+    <td align="center" valign="top">No; default is the current directory.</td>
   </tr>
   <tr>
     <td valign="top">outfile</td>
     <td valign="top">Base name of the test result. The full filename is
       determined by this attribute and the extension of
       <code>formatter</code>.</td>
-    <td align="center" valign="top">No, default is
-      <code>TEST-name</code> using the <code>name</code> attribute.</td>
+    <td align="center" valign="top">No; default is
+      <code>TEST-</code><em>name</em>, where <em>name</em> is the name of
+      the test specified in the <code>name</code> attribute.</td>
   </tr>
   <tr>
     <td valign="top">if</td>
@@ -315,10 +365,10 @@ generates a test class name for each file that ends in
     <td align="center" valign="top">No</td>
   </tr>
 <tr>
-    <td valign="top">errorProperty</td>
+    <td valign="top">errorproperty</td>
     <td valign="top">The name of a property to set in the event of an error.
-      Overrides value set in &lt;junit&gt;.</td>
-    <td align="center" valign="top">No.</td>
+      Overrides value set in <code>&lt;junit&gt;</code>.</td>
+    <td align="center" valign="top">No</td>
 </tr>
   <tr>
     <td valign="top">haltonfailure</td>
@@ -328,21 +378,22 @@ generates a test class name for each file that ends in
     <td align="center" valign="top">No</td>
   </tr>
 <tr>
-    <td valign="top">failureProperty</td>
+    <td valign="top">failureproperty</td>
     <td valign="top">The name of a property to set in the event of a failure
-      (errors are considered failures as well). Overrides value set in &lt;junit&gt;</td>
-    <td align="center" valign="top">No.</td>
+      (errors are considered failures as well). Overrides value set in
+      <code>&lt;junit&gt;</code></td>
+    <td align="center" valign="top">No</td>
 </tr>
   <tr>
     <td valign="top">filtertrace</td>
-    <td valign="top">Filter out junit and ant stack frames from error and failure stack
-    traces.  Overrides value set in &lt;junit&gt;</td>
-    <td align="center" valign="top">No, default is "on."</td>
+    <td valign="top">Filter out Junit and Ant stack frames from error and failure stack
+    traces.  Overrides value set in <code>&lt;junit&gt;</code>.</td>
+    <td align="center" valign="top">No; default is <code>on</code>.</td>
   </tr>
   <tr>
     <td valign="top">todir</td>
     <td valign="top">Directory to write the reports to.</td>
-    <td align="center" valign="top">No, default is current directory.</td>
+    <td align="center" valign="top">No; default is the current directory.</td>
   </tr>
   <tr>
     <td valign="top">if</td>
@@ -351,7 +402,7 @@ generates a test class name for each file that ends in
   </tr>
   <tr>
     <td valign="top">unless</td>
-    <td valign="top">Only run tests if the named property is <b>not</b> set.</td>
+    <td valign="top">Only run tests if the named property is <strong>not</strong> set.</td>
     <td align="center" valign="top">No</td>
   </tr>
 </table>
@@ -378,7 +429,7 @@ VM. No output will be generated unless the test fails.</p>
 </pre>
 
 <p>Runs the test defined in <code>my.test.TestCase</code> in a
-separate VM.  At the end of the test a single line summary will be
+separate VM.  At the end of the test, a one-line summary will be
 printed. A detailed report of the test can be found in
 <code>TEST-my.test.TestCase.txt</code>. The build process will be
 stopped if the test fails.</p>
@@ -405,32 +456,17 @@ stopped if the test fails.</p>
 &lt;/junit&gt;
 </pre>
 
-<p>Runs <code>my.test.TestCase</code> in the same VM (ignoring the
-given CLASSPATH), only a warning is printed if this test fails. In
+<p>Runs <code>my.test.TestCase</code> in the same VM, ignoring the
+given CLASSPATH; only a warning is printed if this test fails. In
 addition to the plain text test results, for this test a XML result
-will be output to <code>result.xml</code>.</p>
-
-<p>For each matching file in the directory <code>${src.tests}</code> a
+will be output to <code>result.xml</code>.  
+Then, for each matching file in the directory defined for
+<code>${src.tests}</code> a
 test is run in a separate VM. If a test fails, the build process is
 aborted. Results are collected in files named
-<code>TEST-<em>name</em>.txt</code> and written to <code>${reports.tests}</code>.</p>
+<code>TEST-</code><em>name</em><code>.txt</code> and written to
+<code>${reports.tests}</code>.</p>
 
-<p>By using the errorProperty and failureProperty attributes, it is possible to
-perform setup work (such as starting an external server), execute the test,
-clean up, and still fail the build in the event of a failure.</p>
-
-<p>The filtertrace attribute condenses error and failure stack traces before reporting them.
-It works with the plain and xml formatters.  It filters out lines that begin with the following
-string patterns:<pre>
-   "junit.framework.TestCase"
-   "junit.framework.TestResult"
-   "junit.framework.TestSuite"
-   "junit.framework.Assert."
-   "junit.swingui.TestRunner"
-   "junit.awtui.TestRunner"
-   "junit.textui.TestRunner"
-   "java.lang.reflect.Method.invoke("
-   "org.apache.tools.ant."</pre></p>
 <hr>
 <p align="center">Copyright &copy; 2001-2002 Apache Software Foundation. All rights
 Reserved.</p>