diff options
Diffstat (limited to 'framework/src/ant/apache-ant-1.9.6/manual/Tasks/junit.html')
| -rw-r--r-- | framework/src/ant/apache-ant-1.9.6/manual/Tasks/junit.html | 802 |
1 files changed, 802 insertions, 0 deletions
diff --git a/framework/src/ant/apache-ant-1.9.6/manual/Tasks/junit.html b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/junit.html new file mode 100644 index 00000000..76df9ced --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/Tasks/junit.html @@ -0,0 +1,802 @@ +<!-- + 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>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> + + +</body> +</html> |