| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <html> |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <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.8.2; it won't |
| work with versions prior to JUnit 3.0. It also works with JUnit 4.0, including |
| "pure" JUnit 4 tests using only annotations and no <code>JUnit4TestAdapter</code>.</p> |
| <p><strong>Note:</strong> This task depends on external libraries not included |
| in the Apache 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> available. |
| You can do one of: |
| </p> |
| <ol> |
| <li> |
| Put both <code>junit.jar</code> and <code>ant-junit.jar</code> 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> |
| Add both JARs to your classpath using <code>-lib</code>. |
| </li> |
| <li> |
| Specify the locations of both JARs using |
| a <code><classpath></code> element in a <code><taskdef></code> in the build file. |
| </li> |
| <li> |
| Leave <code>ant-junit.jar</code> in its default location in <code>ANT_HOME/lib</code> |
| but include <code>junit.jar</code> in the <code><classpath></code> passed |
| to <code><junit></code>. <em>(since Ant 1.7)</em> |
| </li> |
| </ol> |
| <p> |
| See <a href="http://ant.apache.org/faq.html#delegating-classloader" target="_top">the |
| FAQ</a> for details. |
| </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">forkmode</td> |
| <td valign="top">Controls how many Java Virtual Machines get |
| created if you want to fork some tests. Possible values are |
| "perTest" (the default), "perBatch" and |
| "once". "once" creates only a single Java VM |
| for all tests while "perTest" creates a new VM for each |
| TestCase class. "perBatch" creates a VM for each nested |
| <code><batchtest></code> and one collecting all nested |
| <code><test></code>s. Note that only tests with the same |
| settings of <code>filtertrace</code>, <code>haltonerror</code>, |
| <code>haltonfailure</code>, <code>errorproperty</code> and |
| <code>failureproperty</code> can share a VM, so even if you set |
| <code>forkmode</code> to "once", Ant may have to create |
| more than a single Java VM. This attribute is ignored for tests |
| that don't get forked into a new Java VM. <em>since Ant 1.6.2</em></td> |
| <td align="center" valign="top">No; default is <code>perTest</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. When running multiple tests |
| inside the same Java VM (see forkMode), timeout applies to the |
| time that all tests use together, not to an individual |
| test.</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. <strong>Note</strong>: |
| If you get <code>java.lang.OutOfMemoryError: Java heap space</code> |
| in some of your tests then you need to raise the size like |
| <code>maxmemory="128m"</code></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">outputtoformatters</td> |
| <td valign="top"> |
| <em>Since Ant 1.7.0.</em><br/> |
| Send any output generated by tests to the test formatters. |
| This is "true" by default. |
| </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> |
| <tr> |
| <td valign="top">clonevm</td> |
| <td valign="top">If set to true true, then all system properties |
| and the bootclasspath of the forked Java Virtual Machine will be |
| the same as those of the Java VM running Ant. Default is |
| "false" (ignored if fork is disabled). |
| <em>since Ant 1.7</em></td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">logfailedtests</td> |
| <td valign="top">When Ant executes multiple tests and doesn't stop |
| on errors or failures it will log a "FAILED" message for each |
| failing test to its logging system. If you set this option to |
| false, the message will not be logged and you have to rely on the |
| formatter output to find the failing tests. |
| <em>since Ant 1.8.0</em></td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">enableTestListenerEvents</td> |
| <td valign="top">Whether Ant should send fine grained information |
| about the running tests to Ant's logging system at the verbose |
| level. Such events may be used by custom test listeners to show |
| the progress of tests.<br/> |
| Defaults to <code>false</code>.<br/> |
| Can be overridden by a <a href="#enabletestlistenerevents">magic |
| property</a>.<br/> |
| <em>since Ant 1.8.2</em> - <strong>Ant 1.7.0 to 1.8.1 behave as |
| if this attribute was true by default.</strong></td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">threads</td> |
| <td valign="top">a number of threads to run the tests in.<br/> |
| When this attribute is specified the tests will be split arbitrarily among the threads.<br/> |
| requires that the tests be forked with the <code>perTest</code> |
| option to be operative.<br/> |
| <em>since Ant 1.9.4</em></td> |
| <td align="center" valign="top">No</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(" |
| "sun.reflect." |
| "org.apache.tools.ant." |
| "org.junit." |
| "junit.framework.JUnit4TestAdapter" |
| " more"</pre> |
| |
| <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> |
| |
| <p>As of Ant 1.7, this classpath may be used to refer to <code>junit.jar</code> |
| as well as your tests and the tested code. |
| |
| <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="../Tasks/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="../Types/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="../Tasks/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="../Types/permissions.html">permissions</a></p> |
| |
| <p>Settings will be ignored if fork is enabled.</p> |
| |
| <p><em>since Ant 1.6</em>.</p> |
| |
| <h4>assertions</h4> |
| |
| <p>You can control enablement of Java 1.4 assertions with an |
| <a href="../Types/assertions.html"><tt><assertions></tt></a> |
| subelement.</p> |
| |
| <p>Assertion statements are currently ignored in non-forked mode.</p> |
| |
| <p><em>since Ant 1.6.</em></p> |
| |
| <h4>modulepath</h4> |
| |
| <p>The location of modules can be specified using this <a href="../using.html#path">PATH like structure</a>.<br/> |
| The modulepath requires <i>fork</i> to be set to <code>true</code>. |
| |
| <p><em>since Ant 1.10.0</em></p> |
| |
| <h4>upgrademodulepath</h4> |
| |
| <p>The location of modules that replace upgradeable modules in the runtime image |
| can be specified using this <a href="../using.html#path">PATH like structure</a>.<br/> |
| The upgrademodulepath requires <i>fork</i> to be set to <code>true</code>. |
| |
| <p><em>since Ant 1.10.0</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 four 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> |
| |
| <p>The fourth formatter named <code>failure</code> (since Ant 1.8.0) |
| collects all failing <code>testXXX()</code> |
| methods and creates a new <code>TestCase</code> which delegates only these |
| failing methods. The name and the location can be specified via Java System property or Ant property |
| <code>ant.junit.failureCollector</code>. The value has to point to the directory and |
| the name of the resulting class (without suffix). It defaults to <i>java-tmp-dir</i>/FailedTests.</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>, <code>brief</code> or <code>failure</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 <a href="../properties.html#if+unless">if the named property is set</a>.</td> |
| <td align="center">No; default is <code>true</code>.</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Only use formatter <a href="../properties.html#if+unless">if the named property is <b>not</b> set</a>.</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">methods</td> |
| <td valign="top">Comma-separated list of names of test case methods to execute. |
| <em>Since 1.8.2</em> |
| <p>The <code>methods</code> attribute can be useful in the following scenarios:</p> |
| <ul> |
| <li>A test method has failed and you want to re-run the test method |
| to test a fix or re-run the test under the Java debugger without |
| having to wait for the other (possibly long running) test methods |
| to complete.</li> |
| <li>One or more test methods are running slower than expected and you |
| want to re-run them under a Java profiler (without the overhead |
| of running the profiler whilst other test methods are being |
| executed).</li> |
| </ul> |
| <p>If the <code>methods</code> attribute is used but no test method |
| is specified, then no test method from the suite will be executed.</p> |
| </td> |
| <td align="center">No; default is to run all test methods in the suite.</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 <a href="../properties.html#if+unless">if the named property is set</a>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Only run test <a href="../properties.html#if+unless">if the named property is <b>not</b> set</a>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">skipNonTests</td> |
| <td valign="top">Do not pass any classes that do not contain JUnit tests to the test runner. |
| This prevents non tests from appearing as test errors in test results.<br /> |
| Tests are identified by looking for the <code>@Test</code> annotation on any methods in concrete classes |
| that don't extend <code>junit.framework.TestCase</code>, or for public/protected methods with |
| names starting with 'test' in concrete classes that extend <code>junit.framework.TestCase</code>. |
| Classes marked with the JUnit4 <code>org.junit.runner.RunWith</code> or |
| <code>org.junit.runner.Suite.SuiteClasses</code> annotations are also passed to JUnit for execution, |
| as is any class with a public/protected no-argument <code>suite</code> method.</td> |
| <td align="center" valign="top">No. Default is false.</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 <a href="../Types/resources.html">resources</a> from any number |
| of nested <a |
| href="../Types/resources.html#collection">Resource Collection</a>s. It then |
| generates a test class name for each resource that ends in |
| <code>.java</code> or <code>.class</code>.</p> |
| |
| <p>Any type of Resource Collection is supported as a nested element, |
| prior to Ant 1.7 only <code><fileset></code> has been |
| supported.</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 <a href="../properties.html#if+unless">if the named property is set</a>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">unless</td> |
| <td valign="top">Only run tests <a href="../properties.html#if+unless">if the named property is <strong>not</strong> set</a>.</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">skipNonTests</td> |
| <td valign="top">Do not pass any classes that do not contain JUnit tests to the test runner. |
| This prevents non tests from appearing as test errors in test results.<br /> |
| Tests are identified by looking for the <code>@Test</code> annotation on any methods in concrete classes |
| that don't extend <code>junit.framework.TestCase</code>, or for public/protected methods with |
| names starting with 'test' in concrete classes that extend <code>junit.framework.TestCase</code>. |
| Classes marked with the JUnit4 <code>org.junit.runner.RunWith</code> or |
| <code>org.junit.runner.Suite.SuiteClasses</code> annotations are also passed to JUnit for execution, |
| as is any class with a public/protected no-argument <code>suite</code> method.</td> |
| <td align="center" valign="top">No. Default is false.</td> |
| </tr> |
| </table> |
| |
| <p>Batchtests can define their own formatters via nested |
| <code><formatter></code> elements.</p> |
| |
| <h3>Forked tests and <code>tearDown</code></h3> |
| |
| <p>If a forked test runs into a timeout, Ant will terminate the Java |
| VM process it has created, which probably means the |
| test's <code>tearDown</code> method will never be called. The same |
| is true if the forked VM crashes for some other reason.</p> |
| |
| <p>Starting with Ant 1.8.0, a special formatter is distributed with |
| Ant that tries to load the testcase that was in the forked VM and |
| invoke that class' <code>tearDown</code> method. This formatter has |
| the following limitations:</p> |
| |
| <ul> |
| <li>It runs in the same Java VM as Ant itself, this is a different |
| Java VM than the one that was executing the test and it may see a |
| different classloader (and thus may be unable to load the test |
| class).</li> |
| <li>It cannot determine which test was run when the timeout/crash |
| occurred if the forked VM was running multiple test. I.e. the |
| formatter cannot work with any <code>forkMode</code> other |
| than <code>perTest</code> and it won't do anything if the test |
| class contains a <code>suite()</code> method.</li> |
| </ul> |
| |
| <p>If the formatter recognizes an incompatible <code>forkMode</code> |
| or a <code>suite</code> method or fails to load the test class it |
| will silently do nothing.</p> |
| |
| <p>The formatter doesn't have any effect on tests that were not |
| forked or didn't cause timeouts or VM crashes.</p> |
| |
| <p>To enable the formatter, add a <code>formatter</code> like</p> |
| |
| <pre> |
| <formatter classname="org.apache.tools.ant.taskdefs.optional.junit.TearDownOnVmCrash" |
| usefile="false"/> |
| </pre> |
| |
| <p>to your <code>junit</code> task.</p> |
| |
| <h3><a name="enabletestlistenerevents"><code>ant.junit.enabletestlistenerevents</code></a> |
| magic property</h3> |
| |
| <p><em>Since Ant 1.8.2</em> the <code>enableTestListenerEvents</code> |
| attribute of the task controls whether fine grained logging messages |
| will be sent to the task's verbose log. In addition to this |
| attribute Ant will consult the |
| property <code>ant.junit.enabletestlistenerevents</code> and the |
| value of the property overrides the setting of the attribute.</p> |
| |
| <p>This property exists so that containers running Ant that depend on |
| the additional logging events can ensure they will be generated even |
| if the build file disables them.</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> |
| |
| <pre> |
| <target name="test"> |
| <property name="collector.dir" value="${build.dir}/failingTests"/> |
| <property name="collector.class" value="FailedTests"/> |
| <!-- Delete 'old' collector classes --> |
| <delete> |
| <fileset dir="${collector.dir}" includes="${collector.class}*.class"/> |
| </delete> |
| <!-- compile the FailedTests class if present --> |
| <javac srcdir="${collector.dir}" destdir="${collector.dir}"/> |
| <available file="${collector.dir}/${collector.class}.class" property="hasFailingTests"/> |
| <junit haltonerror="false" haltonfailure="false"> |
| <sysproperty key="ant.junit.failureCollector" value="${collector.dir}/${collector.class}"/> |
| <classpath> |
| <pathelement location="${collector.dir}"/> |
| </classpath> |
| <batchtest todir="${collector.dir}" unless="hasFailingTests"> |
| <fileset dir="${collector.dir}" includes="**/*.java" excludes="**/${collector.class}.*"/> |
| <!-- for initial creation of the FailingTests.java --> |
| <formatter type="failure"/> |
| <!-- I want to see something ... --> |
| <formatter type="plain" usefile="false"/> |
| </batchtest> |
| <test name="FailedTests" if="hasFailingTests"> |
| <!-- update the FailingTests.java --> |
| <formatter type="failure"/> |
| <!-- again, I want to see something --> |
| <formatter type="plain" usefile="false"/> |
| </test> |
| </junit> |
| </target> |
| </pre> |
| <p>On the first run all tests are collected via the <code><batchtest/></code> |
| element. Its <code>plain</code> formatter shows the output on the console. The |
| <code>failure</code> formatter creates a java source file in |
| <code>${build.dir}/failingTests/FailedTests.java</code> which extends |
| <code>junit.framework.TestCase</code> and returns from a <code>suite()</code> |
| method a test suite for the failing tests. <br/> |
| On a second run the collector class exists and instead of the <code><batchtest/></code> |
| the single <code><test/></code> will run. So only the failing test cases are re-run. |
| The two nested formatters are for displaying (for the user) and for updating the collector |
| class. |
| </p> |
| <pre> |
| <junit fork="true" |
| jvm="${platform.java}"> |
| <jvmarg value="-Xpatch:${module.name}=${build.test.classes}"/> |
| <jvmarg line="-addmods ${module.name}"/> |
| <jvmarg value="-XaddReads:${module.name}=ALL-UNNAMED"/> |
| <jvmarg value="-XaddExports:${module.name}/my.test=ALL-UNNAMED"/> |
| <classpath> |
| <pathelement path="${libs.junit}"/> |
| </classpath> |
| <modulepath> |
| <pathelement path="${modules}:${build.classes}"/> |
| </modulepath> |
| <formatter type="plain"/> |
| <test name="my.test.TestCase"/> |
| </junit> |
| </pre> |
| <p>Runs my.test.TestCase as a white-box test in the forked VM given by the <code>platform.java</code> property. |
| The junit library is a part of an unnamed module while the tested project and required modules are on the module path. The tests |
| do not have module-info file and are executed in the project module given by <code>module.name</code> property.<br/> |
| The <code>-Xpatch</code> java option executes the tests built into <code>${build.test.classes}</code> in a module given |
| by <code>module.name</code> property.<br/> |
| The <code>-addmods</code> java option enables the tested module.<br/> |
| The <code>-XaddReads</code> java option makes the unnamed module containing the junit readable by tested module.<br/> |
| The <code>-XaddExports</code> java option makes the non-exported test package <code>my.test</code> accessible from the unnamed module containing the junit.<br/> |
| <pre> |
| <junit fork="true" |
| jvm="${platform.java}"> |
| <jvmarg line="-addmods ${test.module.name}"/> |
| <jvmarg value="-XaddExports:${test.module.name}/my.test=junit,ALL-UNNAMED"/> |
| <modulepath> |
| <pathelement path="${modules}:${build.classes}:${libs.junit}"/> |
| </modulepath> |
| <formatter type="plain"/> |
| <test name="my.test.TestCase"/> |
| </junit> |
| </pre> |
| <p>Runs my.test.TestCase as a black-box test in the forked VM given by the <code>platform.java</code> property. |
| The junit library is used as an automatic module. The tests module-info requires the tested module and junit.<br/> |
| The <code>-addmods</code> java option enables the test module.<br/> |
| The <code>-XaddExports</code> java option makes the non-exported test package <code>my.test</code> accessible from the junit module and Ant's test runner. |
| Another possibility is to export the test package in the tests module-info by <code>exports my.test</code> directive.<br/> |
| </body> |
| </html> |