ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hol...@apache.org
Subject cvs commit: jakarta-ant/docs/manual/OptionalTasks junit.html
Date Wed, 20 Mar 2002 00:02:15 GMT
holtdl      02/03/19 16:02:15

  Modified:    docs/manual/OptionalTasks junit.html
  Log:
  Add Stefan's note wrt needing junit.jar and <junit> class files
  in the same classpath. (And the usual compulsive clean-up :)
  
  Revision  Changes    Path
  1.16      +135 -99   jakarta-ant/docs/manual/OptionalTasks/junit.html
  
  Index: junit.html
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/docs/manual/OptionalTasks/junit.html,v
  retrieving revision 1.15
  retrieving revision 1.16
  diff -u -r1.15 -r1.16
  --- junit.html	14 Mar 2002 01:01:18 -0000	1.15
  +++ junit.html	20 Mar 2002 00:02:15 -0000	1.16
  @@ -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 @@
   </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 @@
   <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 @@
   <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 @@
     <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 @@
     <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 @@
   </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 @@
       <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 @@
       <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 @@
       <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 @@
       <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 @@
     </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 @@
   </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 @@
   &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>
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message