| <html> |
| <head> |
| <title>JUnit Task</title> |
| </head> |
| <body> |
| |
| <h2><a name="junit">JUnit</a></h2> |
| <h3>Description</h3> |
| |
| <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 |
| work with versions prior to JUnit 3.0.</p> |
| |
| <p>Tests are defined by nested <code>test</code> or |
| <code>batchtest</code> tags, see <a href="#nested">nested |
| elements</a>.</p> |
| |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </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> |
| </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> |
| </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> |
| </tr> |
| <tr> |
| <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> |
| </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> |
| </tr> |
| <tr> |
| <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> |
| </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 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 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> |
| </tr> |
| <tr> |
| <td valign="top">dir</td> |
| <td valign="top">The directory to invoke the VM in. (ignored if |
| fork 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 |
| disabled.</td> |
| <td align="center" valign="top">No, default is "false".</td> |
| </tr> |
| <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> |
| <td align="center" valign="top">No, default is "true".</td> |
| </tr> |
| </table> |
| |
| <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 |
| 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> |
| |
| <pre> |
| <junit fork="yes"> |
| <jvmarg value="-Djava.compiler=NONE"/> |
| ... |
| </junit> |
| </pre> |
| |
| <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> |
| |
| <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). |
| The attributes for this element are the same as for <a href="../CoreTasks/exec.html#env">environment variables</a>.</p> |
| |
| <pre> |
| <junit fork="no"> |
| <sysproperty key="basedir" value="${basedir}"/> |
| ... |
| </junit> |
| </pre> |
| |
| <p>would run the test in ANT's VM and make the <code>basedir</code> property |
| 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><env></code> elements. See the |
| description in the section about |
| <a href="../CoreTasks/exec.html#env">exec</a></p> |
| |
| <p>Settings will be ignored if fork 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 |
| 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 |
| for all test cases. Custom formatters that need to implement |
| <code>org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter</code> |
| can be specified.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">type</td> |
| <td valign="top">Use a predefined formatter (either |
| "xml", "plain" or "brief").</td> |
| <td align="center" rowspan="2">Exactly one of these.</td> |
| </tr> |
| <tr> |
| <td valign="top">classname</td> |
| <td valign="top">Name of a custom formatter class.</td> |
| </tr> |
| <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> |
| </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> |
| </tr> |
| </table> |
| |
| <h4>test</h4> |
| |
| <p>Defines a single test class.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">name</td> |
| <td valign="top">Name of the test class</td> |
| <td align="center">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">fork</td> |
| <td valign="top">Run the tests in a separate VM. |
| Overrides value set in <code><junit></code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">haltonerror</td> |
| <td valign="top">Stop the build process if an error occurs during the test |
| run. Overrides value set in <code><junit></code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <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> |
| </tr> |
| <tr> |
| <td valign="top">haltonfailure</td> |
| <td valign="top">Stop the build process if a test fails (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">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> |
| </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> |
| </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> |
| </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> |
| </tr> |
| <tr> |
| <td valign="top">if</td> |
| <td valign="top">Only run test if the named property is set.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Only run test if the named property is <b>not</b> set.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| |
| <p>Tests can define their own formatters via nested |
| <code><formatter></code> elements.</p> |
| |
| <h4>batchtest</h4> |
| |
| <p>Define a number of tests based on pattern matching.</p> |
| |
| <p><code>batchtest</code> collects the included files from any number |
| of nested <a |
| href="../CoreTypes/fileset.html"><code><fileset></code></a>s. It then |
| generates a test class name for each file that ends in |
| <code>.java</code> or <code>.class</code>.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td width="12%" valign="top"><b>Attribute</b></td> |
| <td width="78%" valign="top"><b>Description</b></td> |
| <td width="10%" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">fork</td> |
| <td valign="top">Run the tests in a separate VM. |
| Overrides value set in <code><junit></code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">haltonerror</td> |
| <td valign="top">Stop the build process if an error occurs during the test |
| run. Overrides value set in <code><junit></code>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <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> |
| </tr> |
| <tr> |
| <td valign="top">haltonfailure</td> |
| <td valign="top">Stop the build process if a test fails (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">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> |
| </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> |
| </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> |
| </tr> |
| <tr> |
| <td valign="top">if</td> |
| <td valign="top">Only run tests if the named property is set.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Only run tests if the named property is <b>not</b> set.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| </table> |
| |
| <p>Batchtests can define their own formatters via nested |
| <code><formatter></code> elements.</p> |
| |
| <h3>Examples</h3> |
| |
| <pre> |
| <junit> |
| <test name="my.test.TestCase" /> |
| </junit> |
| </pre> |
| |
| <p>Runs the test defined in <code>my.test.TestCase</code> in the same |
| VM. No output will be generated unless the test fails.</p> |
| |
| <pre> |
| <junit printsummary="yes" fork="yes" haltonfailure="yes"> |
| <formatter type="plain" /> |
| <test name="my.test.TestCase" /> |
| </junit> |
| </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 |
| 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> |
| |
| <pre> |
| <junit printsummary="yes" haltonfailure="yes"> |
| <classpath> |
| <pathelement location="${build.tests}" /> |
| <pathelement path="${java.class.path}" /> |
| </classpath> |
| |
| <formatter type="plain" /> |
| |
| <test name="my.test.TestCase" haltonfailure="no" outfile="result" > |
| <formatter type="xml" /> |
| </test> |
| |
| <batchtest fork="yes" todir="${reports.tests}"> |
| <fileset dir="${src.tests}"> |
| <include name="**/*Test*.java" /> |
| <exclude name="**/AllTests.java" /> |
| </fileset> |
| </batchtest> |
| </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 |
| 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 |
| 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> |
| |
| <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> |
| </body> |
| </html> |
