| <html> |
| <head> |
| <title>JUnit Task</title> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/antmanual.css"> |
| </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.8.1; 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="../../faq.html#delegating-classloader" target="_top">the |
| FAQ</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> |
| |
| <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 <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 <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 <code>off</code>.</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 <code>off</code>.</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 <code>on</code>.</td> |
| </tr> |
| <tr> |
| <td valign="top">timeout</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">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 |
| <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 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 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 <code>false</code>.</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 <code>true</code>.</td> |
| </tr> |
| <tr> |
| <td valign="top">showoutput</td> |
| <td valign="top">Send any output generated by tests to Ant's |
| logging system as well as to the formatters. By default only the |
| formatters receive the output.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">tempdir</td> |
| <td valign="top">Where Ant should place temporary files. |
| <em>Since Ant 1.6</em>.</td> |
| <td align="center" valign="top">No; default is the project's base |
| directory.</td> |
| </tr> |
| <tr> |
| <td valign="top">reloading</td> |
| <td valign="top">Whether or not a new classloader should be instantiated for each test case.<br/> |
| Ignore if <code>fork</code> is set to true. |
| <em>Since Ant 1.6</em>.</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>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 <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"> |
| <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, |
| 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> |
| <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>syspropertyset</h4> |
| |
| <p>You can specify a set of properties to be used as system properties |
| with <a href="../CoreTypes/propertyset.html">syspropertyset</a>s.</p> |
| |
| <p><em>since Ant 1.6</em>.</p> |
| |
| <h4>env</h4> |
| |
| <p>It is possible to specify environment variables to pass to the |
| 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 <code>fork</code> is disabled.</p> |
| |
| <h4>bootclasspath</h4> |
| |
| <p>The location of bootstrap class files can be specified using this |
| <a href="../using.html#path">PATH like structure</a> - will be ignored |
| if <i>fork</i> is not <code>true</code> or the target VM doesn't |
| support it (i.e. Java 1.1).</p> |
| |
| <p><em>since Ant 1.6</em>.</p> |
| |
| <h4>permissions</h4> |
| <p>Security permissions can be revoked and granted during the execution of the |
| class via a nested <i>permissions</i> element. For more information please |
| see <a href="../CoreTypes/permissions.html">permissions</a></p> |
| |
| <p>Settings will be ignored if fork is enabled.</p> |
| |
| <p><em>since Ant 1.6</em>.</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 |
| <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 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> |
| |
| <p>If you use the XML formatter, it may not include the same output |
| that your tests have written as some characters are illegal in XML |
| documents and will be dropped.</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 |
| <code>xml</code>, <code>plain</code>, or <code>brief</code>).</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 <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 is <code>true</code>.</td> |
| </tr> |
| <tr> |
| <td valign="top">if</td> |
| <td valign="top">Only use formatter if the named property is set.</td> |
| <td align="center">No; default is <code>true</code>.</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Only use formatter if the named property is <b>not</b> set.</td> |
| <td align="center">No; default is <code>true</code>.</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 <code><junit></code>.</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 |
| <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 <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 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-</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> |
| <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 <code><junit></code>.</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 |
| <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 <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 the 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 <strong>not</strong> 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 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> |
| |
| <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>. |
| 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-</code><em>name</em><code>.txt</code> and written to |
| <code>${reports.tests}</code>.</p> |
| |
| <hr> |
| <p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights |
| Reserved.</p> |
| </body> |
| </html> |
