wangwei
/
antliscence
forked from youys/ant

<html>
<head>
</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.xprogramming.com/software.htm">http://www.xprogramming.com/software.htm</a>.
This task requires JUnit 3.0 or above.</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.</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">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">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 &quot;java&quot;</td>
  </tr>
</table>

<h3><a name="nested">Nested Elements</a></h3>

<p><code>junit</code> supports a nested <code>&lt;classpath&gt;</code>
element, that represents a <a href="index.html#path">PATH like
structure</a>. The value is ignored if <code>fork</code> is
disabled.</p>

<h4>jvmarg</h4>

<p>If fork is enabled, additional parameters may be passed to the new
VM via nested <code>&lt;jvmarg&gt;</code> attributes, for example:</p>

<pre><blockquote>
&lt;junit fork=&quot;yes&quot;&gt;
  &lt;jvmarg value=&quot;-Djava.compiler=NONE&quot;/&gt;
&lt;/junit&gt;
</blockquote></pre>
would run the test in a VM without JIT.</p>

<p><code>&lt;jvmarg&gt;</code> allows all attributes described in <a
href="index.html#arg">Command line arguments</a>.</p>

<h4>formatter</h4>

<p>The results of the tests can be printed in different
formats. Output will always be sent to a file, 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>&lt;test&gt;</code>.

<p>There are two predefined formatters, one prints the test results in
XML format, the other emits plain text. 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" or "plain").</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>
</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>&lt;junit&gt;</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>&lt;junit&gt;</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>&lt;junit&gt;</code>.</td>
    <td align="center" valign="top">No</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>&lt;formatter&gt;</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="index.html#fileset"><code>&lt;fileset&gt;</code></a> and
<code>&lt;filesetref&gt;</code> (referring to a
<code>&lt;fileset&gt;</code> defined elsewhere via its <code>id</code>
attribute) elements. 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>&lt;junit&gt;</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>&lt;junit&gt;</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>&lt;junit&gt;</code>.</td>
    <td align="center" valign="top">No</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>&lt;formatter&gt;</code> elements.</p>

<h3>Examples</h3>
<pre><blockquote>
&lt;junit&gt;
  &lt;test name="my.test.TestCase" /&gt;
&lt;/junit&gt;
</pre></blockquote>

<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><blockquote>
&lt;junit printsummary="yes" fork="yes" haltonfailure="yes"&gt;
  &lt;formatter type="plain" /&gt;
  &lt;test name="my.test.TestCase" /&gt;
&lt;/junit&gt;
</pre></blockquote>

<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><blockquote>
&lt;junit printsummary="yes" haltonfailure="yes"&gt;
  &lt;classpath&gt;
    &lt;pathelement location="${build.tests}" /&gt;
    &lt;pathelement path="${java.class.path}" /&gt;
  &lt;/classpath&gt;

  &lt;formatter type="plain" /&gt;

  &lt;test name="my.test.TestCase" haltonfailure="no" outfile="result" &gt;
    &lt;formatter type="xml" /&gt;
  &lt;/test&gt;

  &lt;batchtest fork="yes"&gt;
    &lt;fileset dir="${src.tests}"&gt;
      &lt;include name="**/*Test*.java" /&gt;
      &lt;exclude name="**/AllTests.java" /&lt;
    &lt;/fileset&gt;
  &lt;/batchtest&gt;
&lt;/junit&gt;
</pre></blockquote>

<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>.</p>

</body>
</html>