diff --git a/docs/manual/OptionalTasks/junit.html b/docs/manual/OptionalTasks/junit.html index cebafc9a2..92f1a791c 100644 --- a/docs/manual/OptionalTasks/junit.html +++ b/docs/manual/OptionalTasks/junit.html @@ -10,16 +10,39 @@

This task runs tests from the JUnit testing framework. The latest version of the framework can be found at http://www.junit.org. -This task has been tested with JUnit 3.0 up to JUnit 3.7, it won't +This task has been tested with JUnit 3.0 up to JUnit 3.7; it won't work with versions prior to JUnit 3.0.

Note: This task depends on external libraries not included in the Ant distribution. See Library Dependencies for more information.

+

+Note: +You must have junit.jar and the class files for the +<junit> task in the same classpath. +You can do one of: +

    +
  1. +Put both junit.jar and the optional tasks jar file in +ANT_HOME/lib. +
    2. +
  2. +Do not put either in ANT_HOME/lib, and instead +include their locations in your CLASSPATH environment variable. +
    3. +
  3. +Do neither of the above, and instead, specify their locations using +a <classpath> element in the build file. + +See the +bugs database for details. +
+

+

Tests are defined by nested test or -batchtest tags, see nested -elements.

+batchtest tags (see nested +elements).

Parameters

@@ -30,97 +53,120 @@ elements.

- - + + - + - + - + - + - + - + - - + + - + - + - - + + - + - - + - - +
printsummaryPrint one line statistics for each testcase. Can - take the values "on", "off" and - "withOutAndErr" - "withOutAndErr" is the same - as "on" but also includes the output of the test - as written to System.out and System.err.No, default is "off"Print one-line statistics for each testcase. Can + take the values on, + off, and + withOutAndErr. + withOutAndErr is the same + as on but also includes the output of the test + as written to System.out and System.err.No; default is off.
fork Run the tests in a separate VM.No, default is "off"No; default is off.
haltonerror Stop the build process if an error occurs during the test run.No, default is "off"No; default is off.
errorPropertyerrorproperty The name of a property to set in the event of an error.No.No
haltonfailure Stop the build process if a test fails (errors are considered failures as well).No, default is "off"No; default is off.
failurePropertyfailureproperty The name of a property to set in the event of a failure (errors are considered failures as well). No.
filtertraceFilter out junit and ant stack frames from error and failure stack traces.No, default is "on."Filter out Junit and Ant stack frames from error and failure stack traces.No; default is on.
timeoutCancel the individual tests if the don't finish - in the given time (measured in milliseconds). Ignored if fork is - disabled.Cancel the individual tests if they don't finish + in the given time (measured in milliseconds). Ignored if + fork is disabled. No
maxmemoryMax amount of memory to allocate to the forked VM - (ignored if fork is disabled)Maximum amount of memory to allocate to the forked VM. + Ignored if fork is disabled. No
jvmthe 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.No, default "java"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.No; default is java.
dirThe directory to invoke the VM in. (ignored if - fork is disabled)The directory in which to invoke the VM. Ignored if + fork is disabled. No
newenvironmentDo not propagate old environment when new - environment variables are specified. Ignored if fork is + Do not propagate the old environment when new + environment variables are specified. Ignored if fork is disabled.No, default is "false".No; default is false.
includeantruntimeimplicitly add the Ant classes required to run + Implicitly add the Ant classes required to run the tests and JUnit to the classpath in forked mode.No, default is "true".No; default is true.
+

By using the errorproperty and failureproperty +attributes, it is possible to +perform setup work (such as starting an external server), execute the test, +clean up, and still fail the build in the event of a failure.

+ +

The filtertrace 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:

+   "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."

+

Nested Elements

-

junit supports a nested <classpath> -element, that represents a PATH like +

The <junit> task +supports a nested <classpath> +element that represents a PATH like structure.

jvmarg

-

If fork is enabled, additional parameters may be passed to the new -VM via nested <jvmarg> attributes, for example:

+

If fork is enabled, additional parameters may be passed to +the new VM via nested <jvmarg> elements. For example:

 <junit fork="yes">
@@ -132,13 +178,14 @@ VM via nested <jvmarg> attributes, for example:

 
would run the test in a VM without JIT.

 
 
<jvmarg> allows all attributes described in Command line arguments.

+href="../using.html#arg">Command-line Arguments.

 
 
sysproperty

 
 
Use nested <sysproperty> 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).
+to the VM during the execution of the test (either ANT's VM or the forked VM,
+if fork is enabled).
 The attributes for this element are the same as for environment variables.

 
 
@@ -155,24 +202,25 @@ available to the test.

 
env

 
 
It is possible to specify environment variables to pass to the
-forked VM via nested <env> elements. See the
-description in the section about
-exec

+forked VM via nested <env> elements. For a description
+of the <env> element's attributes, see the
+description in the exec task.

 
-
Settings will be ignored if fork is disabled.

+
Settings will be ignored if fork is disabled.

 
 
formatter

 
 
The results of the tests can be printed in different
-formats. Output will always be sent to a file unless you set the
-usefile attribute to false, the name of the file is determined by the
+formats. Output will always be sent to a file, unless you set the
+usefile attribute to false.
+The name of the file is determined by the
 name of the test and can be set by the outfile attribute
 of <test>.

 
-
There are three predefined formatters, one prints the test results
-in XML format, the other emit plain text.  The formatter named
-"brief" will only print detailed information for testcases
-that failed, while "plain" gives a little statistics line
+
There are three predefined formatters - one prints the test results
+in XML format, the other emits plain text.  The formatter named
+brief will only print detailed information for testcases
+that failed, while plain gives a little statistics line
 for all test cases.  Custom formatters that need to implement
 org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter
 can be specified.

@@ -186,7 +234,7 @@ can be specified.

   
     type
     Use a predefined formatter (either
-      "xml", "plain" or "brief").
+      xml, plain, or brief).
     Exactly one of these.
   
   
@@ -196,13 +244,13 @@ can be specified.

   
     extension
     Extension to append to the output filename.
-    Yes, if classname has been used.
+    Yes, if classname has been used.
   
   
     usefile
     Boolean that determines whether output should be
       sent to a file.
-    No, default true.
+    No; default is true.
   
 
 
@@ -218,7 +266,7 @@ can be specified.

 
   
     name
-    Name of the test class
+    Name of the test class.
     Yes
   
   
@@ -234,10 +282,10 @@ can be specified.

     No
   
 
-    errorProperty
+    errorproperty
     The name of a property to set in the event of an error.
-      Overrides value set in <junit>.
-    No.
+      Overrides value set in <junit>.
+    No
 
   
     haltonfailure
@@ -247,29 +295,31 @@ can be specified.

     No
   
 
-    failureProperty
+    failureproperty
     The name of a property to set in the event of a failure
-      (errors are considered failures as well). Overrides value set in <junit>.
-    No.
+      (errors are considered failures as well). Overrides value set in
+      <junit>.
+    No
 
   
     filtertrace
-    Filter out junit and ant stack frames from error and failure stack
-    traces.  Overrides value set in <junit>
-    No, default is "on."
+    Filter out Junit and Ant stack frames from error and failure stack
+    traces.  Overrides value set in <junit>.
+    No; default is on.
   
   
     todir
     Directory to write the reports to.
-    No, default is current directory.
+    No; default is the current directory.
   
   
     outfile
     Base name of the test result. The full filename is
       determined by this attribute and the extension of
       formatter.
-    No, default is
-      TEST-name using the name attribute.
+    No; default is
+      TEST-name, where name is the name of
+      the test specified in the name attribute.
   
   
     if
@@ -315,10 +365,10 @@ generates a test class name for each file that ends in
     No
   
 
-    errorProperty
+    errorproperty
     The name of a property to set in the event of an error.
-      Overrides value set in <junit>.
-    No.
+      Overrides value set in <junit>.
+    No
 
   
     haltonfailure
@@ -328,21 +378,22 @@ generates a test class name for each file that ends in
     No
   
 
-    failureProperty
+    failureproperty
     The name of a property to set in the event of a failure
-      (errors are considered failures as well). Overrides value set in <junit>
-    No.
+      (errors are considered failures as well). Overrides value set in
+      <junit>
+    No
 
   
     filtertrace
-    Filter out junit and ant stack frames from error and failure stack
-    traces.  Overrides value set in <junit>
-    No, default is "on."
+    Filter out Junit and Ant stack frames from error and failure stack
+    traces.  Overrides value set in <junit>.
+    No; default is on.
   
   
     todir
     Directory to write the reports to.
-    No, default is current directory.
+    No; default is the current directory.
   
   
     if
@@ -351,7 +402,7 @@ generates a test class name for each file that ends in
   
   
     unless
-    Only run tests if the named property is not set.
+    Only run tests if the named property is not set.
     No
   
 
@@ -378,7 +429,7 @@ VM. No output will be generated unless the test fails.

 

 
 
Runs the test defined in my.test.TestCase in a
-separate VM.  At the end of the test a single line summary will be
+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
 TEST-my.test.TestCase.txt. The build process will be
 stopped if the test fails.

@@ -405,32 +456,17 @@ stopped if the test fails.

 </junit>
-

Runs my.test.TestCase in the same VM (ignoring the -given CLASSPATH), only a warning is printed if this test fails. In +

Runs my.test.TestCase 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 result.xml.

- -

For each matching file in the directory ${src.tests} a +will be output to result.xml. +Then, for each matching file in the directory defined for +${src.tests} a test is run in a separate VM. If a test fails, the build process is aborted. Results are collected in files named -TEST-name.txt and written to ${reports.tests}.

+TEST-name.txt and written to +${reports.tests}.

-

By using the errorProperty and failureProperty attributes, it is possible to -perform setup work (such as starting an external server), execute the test, -clean up, and still fail the build in the event of a failure.

- -

The filtertrace attribute condenses error and failure stack traces before reporting them. -It works with the plain and xml formatters. It filters out lines that begin with the following -string patterns:

-   "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."

Copyright © 2001-2002 Apache Software Foundation. All rights Reserved.