Google

JUnitTask (Apache Ant API)
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

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

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

Since:
Ant 1.2
Version:
$Revision: 1.44.2.1 $
Author:
Thomas Haas
, Stefan Bodewig , Stephane Bailliez , Gerrit Riessen , Erik Hatcher
See Also:
JUnitTest, BatchTest

Nested Class Summary
static class JUnitTask.SummaryAttribute
          Print summary enumeration values.
 
Field Summary
 
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 addEnv(Environment.Variable var)
          Adds an environment variable; used when forking.
 void addFormatter(FormatterElement fe)
          Add a new formatter to all tests of this task.
 void addSysproperty(Environment.Variable sysp)
          Adds a system property that tests can access.
 void addTest(JUnitTest test)
          Add a new single testcase.
protected  java.util.Enumeration allTests()
           
 BatchTest createBatchTest()
          Adds a set of tests based on pattern matching.
 Path createClasspath()
          Adds path to classpath used for tests.
 Commandline.Argument createJvmarg()
          Adds a JVM argument; ignored if not forking.
protected  ExecuteWatchdog createWatchdog()
           
 void execute()
          Runs the testcase.
protected  void execute(JUnitTest arg)
          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)
          If the formatter sends output to a file, return that file.
protected  void handleErrorOutput(java.lang.String line)
          Pass output sent to System.err to the TestRunner so it can collect ot for the formatters.
protected  void handleOutput(java.lang.String line)
          Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
 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 them directly.
 void setDir(java.io.File dir)
          The directory to invoke the VM in.
 void setErrorProperty(java.lang.String propertyName)
          Property to set to "true" if there is a error in a test.
 void setFailureProperty(java.lang.String propertyName)
          Property to set to "true" if there is a failure in a test.
 void setFiltertrace(boolean value)
          If true, smartly filter the stack frames of JUnit errors and failures before reporting them.
 void setFork(boolean value)
          If true, JVM should be forked for each test.
 void setHaltonerror(boolean value)
          If true, stop the build process when there is an error in a test.
 void setHaltonfailure(boolean value)
          If true, stop the build process if a test fails (errors are considered failures as well).
 void setIncludeantruntime(boolean b)
          If true, include ant.jar, optional.jar and junit.jar in the forked VM.
 void setJvm(java.lang.String value)
          The command used to invoke the Java Virtual Machine, default is 'java'.
 void setMaxmemory(java.lang.String max)
          Set the maximum memory to be used by all forked JVMs.
 void setNewenvironment(boolean newenv)
          If true, use a new environment when forked.
 void setPrintsummary(JUnitTask.SummaryAttribute value)
          If true, print one-line statistics for each test, or "withOutAndErr" to also show standard output and error.
 void setShowOutput(boolean showOutput)
          If true, send any output generated by tests to Ant's logging system as well as to the formatters.
 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, isInvalid, 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.

Since:
Ant 1.2
Method Detail

setFiltertrace


public void setFiltertrace(boolean value)
If true, smartly filter the stack frames of JUnit errors and failures before reporting them.

This property is applied on all BatchTest (batchtest) and JUnitTest (test) however it can possibly be overridden by their own properties.

Parameters:
value - false if it should not filter, otherwise true
Since:
Ant 1.5

setHaltonerror


public void setHaltonerror(boolean value)
If true, stop the build process 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
Since:
Ant 1.2

setErrorProperty


public void setErrorProperty(java.lang.String propertyName)
Property to set to "true" if 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:
propertyName - the name of the property to set in the event of an error.
Since:
Ant 1.4

setHaltonfailure


public void setHaltonfailure(boolean value)
If true, stop the build process if a test fails (errors are considered failures as well). 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
Since:
Ant 1.2

setFailureProperty


public void setFailureProperty(java.lang.String propertyName)
Property to set to "true" if 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:
propertyName - the name of the property to set in the event of an failure.
Since:
Ant 1.4

setFork


public void setFork(boolean value)
If true, JVM should be forked for each test.

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
Since:
Ant 1.2
See Also:
setTimeout(java.lang.Integer)

setPrintsummary


public void setPrintsummary(JUnitTask.SummaryAttribute value)
If true, print one-line statistics for each test, or "withOutAndErr" to also show standard output and error. Can take the values on, off, and withOutAndErr.

Parameters:
value - true to print a summary, withOutAndErr to include the test's output as well, false otherwise.
Since:
Ant 1.2
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'
Since:
Ant 1.2
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.
Since:
Ant 1.2

setJvm


public void setJvm(java.lang.String value)
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.

Parameters:
value - the new VM to use instead of java
Since:
Ant 1.2
See Also:
setFork(boolean)

createJvmarg


public Commandline.Argument createJvmarg()
Adds a JVM argument; ignored if not forking.

Returns:
create a new JVM argument so that any argument can be passed to the JVM.
Since:
Ant 1.2
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.
Since:
Ant 1.2
See Also:
setFork(boolean)

addSysproperty


public void addSysproperty(Environment.Variable sysp)
Adds a system property that tests can access. This might be useful to tranfer Ant properties to the testcases when JVM forking is not enabled.

Since:
Ant 1.3

createClasspath


public Path createClasspath()
Adds path to classpath used for tests.

Since:
Ant 1.2

addEnv


public void addEnv(Environment.Variable var)
Adds an environment variable; used when forking.

Will be ignored if we are not forking a new VM.

Since:
Ant 1.5

setNewenvironment


public void setNewenvironment(boolean newenv)
If true, use a new environment when forked.

Will be ignored if we are not forking a new VM.

Since:
Ant 1.5

addTest


public void addTest(JUnitTest test)
Add a new single testcase.

Parameters:
test - a new single testcase
Since:
Ant 1.2
See Also:
JUnitTest

createBatchTest


public BatchTest createBatchTest()
Adds a set of tests based on pattern matching.

Returns:
a new instance of a batch test.
Since:
Ant 1.2
See Also:
BatchTest

addFormatter


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

Since:
Ant 1.2

setIncludeantruntime


public void setIncludeantruntime(boolean b)
If true, include ant.jar, optional.jar and junit.jar in the forked VM.

Since:
Ant 1.5

setShowOutput


public void setShowOutput(boolean showOutput)
If true, 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.

Output will always be passed to the formatters and not by shown by default. This option should for example be set for tests that are interactive and prompt the user to do something.

Since:
Ant 1.5

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 them directly.

Overrides:
init in class Task
Since:
Ant 1.4

execute


public void execute()
             throws BuildException
Runs the testcase.

Overrides:
execute in class Task
Throws:
BuildException - if something goes wrong with the build
Since:
Ant 1.2

execute


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

BuildException

handleOutput


protected void handleOutput(java.lang.String line)
Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.

Overrides:
handleOutput in class Task
Parameters:
line - The line of output to log. Should not be null.
Since:
Ant 1.5

handleErrorOutput


protected void handleErrorOutput(java.lang.String line)
Pass output sent to System.err to the TestRunner so it can collect ot for the formatters.

Overrides:
handleErrorOutput in class Task
Parameters:
line - The error line to log. Should not be null.
Since:
Ant 1.5

createWatchdog


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

getDefaultOutput


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

Since:
Ant 1.3

getIndividualTests


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

Since:
Ant 1.3

allTests


protected java.util.Enumeration allTests()
Since:
Ant 1.3

getOutput


protected java.io.File getOutput(FormatterElement fe,
                                 JUnitTest test)
If the formatter sends output to a file, return that file. null otherwise.

Since:
Ant 1.3

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.

Since:
Ant 1.4
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2000-2002 Apache Software Foundation. All Rights Reserved.