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><junit></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><classpath></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 "on", "off" and - "withOutAndErr" - "withOutAndErr" is the same - as "on" 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'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 "java"</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 "false".</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 "true".</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><classpath></code> -element, that represents a <a href="../using.html#path">PATH like +<p>The <code><junit></code> task +supports a nested <code><classpath></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><jvmarg></code> attributes, for example:</p> +<p>If <code>fork</code> is enabled, additional parameters may be passed to +the new VM via nested <code><jvmarg></code> elements. For example:</p> <pre> <junit fork="yes"> @@ -132,13 +178,14 @@ <p>would run the test in a VM without JIT.</p> <p><code><jvmarg></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><sysproperty></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><env></code> elements. See the -description in the section about -<a href="../CoreTasks/exec.html#env">exec</a></p> +forked VM via nested <code><env></code> elements. For a description +of the <code><env></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><test></code>.</p> -<p>There are three predefined formatters, one prints the test results -in XML format, the other emit plain text. The formatter named -"brief" will only print detailed information for testcases -that failed, while "plain" 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 - "xml", "plain" or "brief").</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 <junit>.</td> - <td align="center" valign="top">No.</td> + Overrides value set in <code><junit></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 <junit>.</td> - <td align="center" valign="top">No.</td> + (errors are considered failures as well). Overrides value set in + <code><junit></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 <junit></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><junit></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 <junit>.</td> - <td align="center" valign="top">No.</td> + Overrides value set in <code><junit></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 <junit></td> - <td align="center" valign="top">No.</td> + (errors are considered failures as well). Overrides value set in + <code><junit></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 <junit></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><junit></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 @@ </junit> </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 © 2001-2002 Apache Software Foundation. All rights Reserved.</p>
-- To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]> For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
