org.apache.tools.ant.taskdefs.optional.junit
Class JUnitTask

java.lang.Object
  |
  +--org.apache.tools.ant.ProjectComponent
        |
        +--org.apache.tools.ant.Task
              |
              +--org.apache.tools.ant.taskdefs.optional.junit.JUnitTask

public class JUnitTask
extends Task

Ant task to run JUnit tests.

JUnit is a framework to create unit test. It has been initially created by Erich Gamma and Kent Beck. JUnit can be found at http://www.junit.org.

JUnitTask can run a single specific JUnitTest using the test element. For example, the following target

   <target name="test-int-chars" depends="jar-test">
       <echo message="testing international characters"/>
       <junit printsummary="no" haltonfailure="yes" fork="false">
           <classpath refid="classpath"/>
           <formatter type="plain" usefile="false" />
           <test name="org.apache.ecs.InternationalCharTest" />
       </junit>
   </target>
 
runs a single junit test (org.apache.ecs.InternationalCharTest) in the current VM using the path with id classpath as classpath and presents the results formatted using the standard plain formatter on the command line.

This task can also run batches of tests. The batchtest element creates a BatchTest based on a fileset. This allows, for example, all classes found in directory to be run as testcases. For example,

 <target name="run-tests" depends="dump-info,compile-tests" if="junit.present">
   <junit printsummary="no" haltonfailure="yes" fork="${junit.fork}">
     <jvmarg value="-classic"/>
     <classpath refid="tests-classpath"/>
     <sysproperty key="build.tests" value="${build.tests}"/>
     <formatter type="brief" usefile="false" />
     <batchtest>
       <fileset dir="${tests.dir}">
         <include name="**/*Test*" />
       </fileset>
     </batchtest>
   </junit>
 </target>
 
this target finds any classes with a test directory anywhere in their path (under the top ${tests.dir}, of course) and creates JUnitTest's for each one.

Of course, <junit> and <batch> elements can be combined for more complex tests. For an example, see the ant build.xml target run-tests (the second example is an edited version).

To spawn a new Java VM to prevent interferences between different testcases, you need to enable fork. A number of attributes and elements allow you to set up how this JVM runs.

Author:
Thomas Haas, Stefan Bodewig, Stephane Bailliez, Gerrit Riessen, Erik Hatcher
See Also:
JUnitTest, BatchTest

Inner Class Summary
static class JUnitTask.SummaryAttribute
          Print summary enumeration values.
 
Fields inherited from class org.apache.tools.ant.Task
description, location, target, taskName, taskType, wrapper
 
Fields inherited from class org.apache.tools.ant.ProjectComponent
project
 
Constructor Summary
JUnitTask()
          Creates a new JUnitRunner and enables fork of a new Java VM.
 
Method Summary
protected  void addClasspathEntry(java.lang.String resource)
          Search for the given resource and add the directory or archive that contains it to the classpath.
 void addFormatter(FormatterElement fe)
          Add a new formatter to all tests of this task.
 void addSysproperty(Environment.Variable sysp)
          Add a nested sysproperty element.
 void addTest(JUnitTest test)
          Add a new single testcase.
protected  java.util.Enumeration allTests()
           
 BatchTest createBatchTest()
          Create a new set of testcases (also called ..batchtest) and add it to the list.
 Path createClasspath()
          <classpath> allows classpath to be set for tests.
 Commandline.Argument createJvmarg()
          Create a new JVM argument.
protected  ExecuteWatchdog createWatchdog()
           
 void execute()
          Runs the testcase.
protected  void execute(JUnitTest test)
          Run the tests.
protected  java.io.OutputStream getDefaultOutput()
          Get the default output for a formatter.
protected  java.util.Enumeration getIndividualTests()
          Merge all individual tests from the batchtest with all individual tests and return an enumeration over all JUnitTest.
protected  java.io.File getOutput(FormatterElement fe, JUnitTest test)
          return the file or null if does not use a file
protected  void handleErrorOutput(java.lang.String line)
           
protected  void handleOutput(java.lang.String line)
           
 void init()
          Adds the jars or directories containing Ant, this task and JUnit to the classpath - this should make the forked JVM work without having to specify the directly.
 void setDir(java.io.File dir)
          The directory to invoke the VM in.
 void setErrorProperty(java.lang.String propertyName)
          Tells this task to set the named property to "true" when there is a error in a test.
 void setFailureProperty(java.lang.String propertyName)
          Tells this task to set the named property to "true" when there is a failure in a test.
 void setFork(boolean value)
          Tells whether a JVM should be forked for each testcase.
 void setHaltonerror(boolean value)
          Tells this task to halt when there is an error in a test.
 void setHaltonfailure(boolean value)
          Tells this task to halt when there is a failure in a test.
 void setJvm(java.lang.String value)
          Set a new VM to execute the testcase.
 void setMaxmemory(java.lang.String max)
          Set the maximum memory to be used by all forked JVMs.
 void setPrintsummary(JUnitTask.SummaryAttribute value)
          Tells whether the task should print a short summary of the task.
 void setTimeout(java.lang.Integer value)
          Set the timeout value (in milliseconds).
 
Methods inherited from class org.apache.tools.ant.Task
getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, log, log, maybeConfigure, perform, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName
 
Methods inherited from class org.apache.tools.ant.ProjectComponent
getProject, setProject
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

JUnitTask

public JUnitTask()
          throws java.lang.Exception
Creates a new JUnitRunner and enables fork of a new Java VM.
Method Detail

setHaltonerror

public void setHaltonerror(boolean value)
Tells this task to halt when there is an error in a test. this property is applied on all BatchTest (batchtest) and JUnitTest (test) however it can possibly be overridden by their own properties.
Parameters:
value - true if it should halt, otherwise false

setErrorProperty

public void setErrorProperty(java.lang.String propertyName)
Tells this task to set the named property to "true" when there is a error in a test. This property is applied on all BatchTest (batchtest) and JUnitTest (test), however, it can possibly be overriden by their own properties.
Parameters:
value - the name of the property to set in the event of an error.

setHaltonfailure

public void setHaltonfailure(boolean value)
Tells this task to halt when there is a failure in a test. this property is applied on all BatchTest (batchtest) and JUnitTest (test) however it can possibly be overridden by their own properties.
Parameters:
value - true if it should halt, otherwise false

setFailureProperty

public void setFailureProperty(java.lang.String propertyName)
Tells this task to set the named property to "true" when there is a failure in a test. This property is applied on all BatchTest (batchtest) and JUnitTest (test), however, it can possibly be overriden by their own properties.
Parameters:
value - the name of the property to set in the event of an failure.

setFork

public void setFork(boolean value)
Tells whether a JVM should be forked for each testcase. It avoids interference between testcases and possibly avoids hanging the build. this property is applied on all BatchTest (batchtest) and JUnitTest (test) however it can possibly be overridden by their own properties.
Parameters:
value - true if a JVM should be forked, otherwise false
See Also:
setTimeout(java.lang.Integer)

setPrintsummary

public void setPrintsummary(JUnitTask.SummaryAttribute value)
Tells whether the task should print a short summary of the task.
Parameters:
value - true to print a summary, withOutAndErr to include the test's output as well, false otherwise.
See Also:
SummaryJUnitResultFormatter

setTimeout

public void setTimeout(java.lang.Integer value)
Set the timeout value (in milliseconds). If the test is running for more than this value, the test will be canceled. (works only when in 'fork' mode).
Parameters:
value - the maximum time (in milliseconds) allowed before declaring the test as 'timed-out'
See Also:
setFork(boolean)

setMaxmemory

public void setMaxmemory(java.lang.String max)
Set the maximum memory to be used by all forked JVMs.
Parameters:
max - the value as defined by -mx or -Xmx in the java command line options.

setJvm

public void setJvm(java.lang.String value)
Set a new VM to execute the testcase. Default is java. Ignored if no JVM is forked.
Parameters:
value - the new VM to use instead of java
See Also:
setFork(boolean)

createJvmarg

public Commandline.Argument createJvmarg()
Create a new JVM argument. Ignored if no JVM is forked.
Returns:
create a new JVM argument so that any argument can be passed to the JVM.
See Also:
setFork(boolean)

setDir

public void setDir(java.io.File dir)
The directory to invoke the VM in. Ignored if no JVM is forked.
Parameters:
dir - the directory to invoke the JVM from.
See Also:
setFork(boolean)

addSysproperty

public void addSysproperty(Environment.Variable sysp)
Add a nested sysproperty element. This might be useful to tranfer Ant properties to the testcases when JVM forking is not enabled.

createClasspath

public Path createClasspath()
<classpath> allows classpath to be set for tests.

addTest

public void addTest(JUnitTest test)
Add a new single testcase.
Parameters:
test - a new single testcase
See Also:
JUnitTest

createBatchTest

public BatchTest createBatchTest()
Create a new set of testcases (also called ..batchtest) and add it to the list.
Returns:
a new instance of a batch test.
See Also:
BatchTest

addFormatter

public void addFormatter(FormatterElement fe)
Add a new formatter to all tests of this task.

init

public void init()
Adds the jars or directories containing Ant, this task and JUnit to the classpath - this should make the forked JVM work without having to specify the directly.
Overrides:
init in class Task
Following copied from class: org.apache.tools.ant.Task
Throws:
BuildException - if someting goes wrong with the build

execute

public void execute()
             throws BuildException
Runs the testcase.
Overrides:
execute in class Task
Following copied from class: org.apache.tools.ant.Task
Throws:
BuildException - if someting goes wrong with the build

execute

protected void execute(JUnitTest test)
                throws BuildException
Run the tests.

handleOutput

protected void handleOutput(java.lang.String line)
Overrides:
handleOutput in class Task

handleErrorOutput

protected void handleErrorOutput(java.lang.String line)
Overrides:
handleErrorOutput in class Task

createWatchdog

protected ExecuteWatchdog createWatchdog()
                                  throws BuildException
Returns:
null if there is a timeout value, otherwise the watchdog instance.

getDefaultOutput

protected java.io.OutputStream getDefaultOutput()
Get the default output for a formatter.

getIndividualTests

protected java.util.Enumeration getIndividualTests()
Merge all individual tests from the batchtest with all individual tests and return an enumeration over all JUnitTest.

allTests

protected java.util.Enumeration allTests()

getOutput

protected java.io.File getOutput(FormatterElement fe,
                                 JUnitTest test)
return the file or null if does not use a file

addClasspathEntry

protected void addClasspathEntry(java.lang.String resource)
Search for the given resource and add the directory or archive that contains it to the classpath.

Doesn't work for archives in JDK 1.1 as the URL returned by getResource doesn't contain the name of the archive.



Copyright © 1999-2002 Apache Software Foundation. All Rights Reserved.