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

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

Since:
Ant 1.2

See Also:
JUnitTest, BatchTest

Nested Class Summary

static class
JUnitTask.ForkMode
These are the different forking options
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
actOnTestResult(int exitValue, boolean wasKilled, JUnitTest test, String name)
Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occured or sets a property.
void
addAssertions(Assertions asserts)
Assertions to enable in this program (if fork=true)
protected void
addClasspathEntry(String resource)
Search for the given resource and add the directory or archive that contains it to the classpath.
void
addConfiguredSysproperty(Environment.Variable sysp)
Adds a system property that tests can access.
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)
Deprecated. since ant 1.6
void
addSyspropertyset(PropertySet sysp)
Adds a set of properties that will be used as system properties that tests can access.
void
addTest(JUnitTest test)
Add a new single testcase.
protected Enumeration
allTests()
return an enumeration listing each test, then each batchtest
BatchTest
createBatchTest()
Adds a set of tests based on pattern matching.
Path
createBootclasspath()
Adds a path to the bootclasspath.
Path
createClasspath()
Adds path to classpath used for tests.
Commandline.Argument
createJvmarg()
Adds a JVM argument; ignored if not forking.
Permissions
createPermissions()
Sets the permissions for the application run inside the same JVM.
protected ExecuteWatchdog
createWatchdog()
void
execute()
Runs the testcase.
protected void
execute(List tests)
Execute a list of tests in a single forked Java VM.
protected void
execute(JUnitTest arg)
Run the tests.
protected Collection
executeOrQueue(Enumeration testList, boolean runIndividual)
Executes all tests that don't need to be forked (or all tests if the runIndividual argument is true.
protected CommandlineJava
getCommandline()
protected OutputStream
getDefaultOutput()
Get the default output for a formatter.
protected Enumeration
getIndividualTests()
Merge all individual tests from the batchtest with all individual tests and return an enumeration over all JUnitTest.
protected File
getOutput(FormatterElement fe, JUnitTest test)
If the formatter sends output to a file, return that file.
void
handleErrorFlush(String output)
Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
void
handleErrorOutput(String output)
Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
protected void
handleFlush(String output)
Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
protected int
handleInput(byte[] buffer, int offset, int length)
protected void
handleOutput(String output)
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(File dir)
The directory to invoke the VM in.
void
setErrorProperty(String propertyName)
Property to set to "true" if there is a error in a test.
void
setFailureProperty(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
setForkMode(JUnitTask.ForkMode mode)
Set the behavior when fork fork has been enabled.
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(String value)
The command used to invoke the Java Virtual Machine, default is 'java'.
void
setMaxmemory(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
setReloading(boolean value)
If true, force ant to re-classload all classes for each JUnit TestCase
void
setShowOutput(boolean showOutput)
If true, send any output generated by tests to Ant's logging system as well as to the formatters.
void
setTempdir(File tmpDir)
Where Ant should place temporary files.
void
setTimeout(Integer value)
Set the timeout value (in milliseconds).

Methods inherited from class org.apache.tools.ant.Task

execute, getDescription, getLocation, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, maybeConfigure, perform, reconfigure, setDescription, setLocation, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType

Methods inherited from class org.apache.tools.ant.ProjectComponent

getProject, log, log, setProject

Constructor Details

JUnitTask

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

Since:
Ant 1.2

Method Details

actOnTestResult

protected void actOnTestResult(int exitValue,
                               boolean wasKilled,
                               JUnitTest test,
                               String name)
Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occured or sets a property.

Since:
Ant 1.6.2


addAssertions

public void addAssertions(Assertions asserts)
Assertions to enable in this program (if fork=true)

Parameters:
asserts - assertion set

Since:
Ant 1.6


addClasspathEntry

protected void addClasspathEntry(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.

Parameters:
resource - resource that one wants to lookup

Since:
Ant 1.4


addConfiguredSysproperty

public void addConfiguredSysproperty(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.

Parameters:
sysp - new environment variable to add

Since:
Ant 1.6


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.

Parameters:
var - environment variable to be added

Since:
Ant 1.5


addFormatter

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

Parameters:
fe - formatter element

Since:
Ant 1.2


addSysproperty

public void addSysproperty(Environment.Variable sysp)

Deprecated. since ant 1.6

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.

Parameters:
sysp - environment variable to add

Since:
Ant 1.3


addSyspropertyset

public void addSyspropertyset(PropertySet sysp)
Adds a set of properties that will be used as system properties that tests can access. This might be useful to tranfer Ant properties to the testcases when JVM forking is not enabled.

Parameters:
sysp - set of properties to be added

Since:
Ant 1.6


addTest

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

Parameters:
test - a new single testcase

Since:
Ant 1.2

See Also:
JUnitTest


allTests

protected Enumeration allTests()
return an enumeration listing each test, then each batchtest

Returns:
enumeration

Since:
Ant 1.3


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


createBootclasspath

public Path createBootclasspath()
Adds a path to the bootclasspath.

Returns:
reference to the bootclasspath in the embedded java command line

Since:
Ant 1.6


createClasspath

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

Returns:
reference to the classpath in the embedded java command line

Since:
Ant 1.2


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)


createPermissions

public Permissions createPermissions()
Sets the permissions for the application run inside the same JVM.

Returns:
.

Since:
Ant 1.6


createWatchdog

protected ExecuteWatchdog createWatchdog()
            throws BuildException

Returns:
null if there is a timeout value, otherwise the watchdog instance.

Throws:
BuildException - under unspecified circumstances

Since:
Ant 1.2


execute

public void execute()
            throws BuildException
Runs the testcase.
Overrides:
execute in interface Task

Throws:
BuildException - in case of test failures or errors

Since:
Ant 1.2


execute

protected void execute(List tests)
            throws BuildException
Execute a list of tests in a single forked Java VM.


execute

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

Parameters:
arg - one JunitTest

Throws:
BuildException - in case of test failures or errors


executeOrQueue

protected Collection executeOrQueue(Enumeration testList,
                                    boolean runIndividual)
Executes all tests that don't need to be forked (or all tests if the runIndividual argument is true. Returns a collection of lists of tests that share the same VM configuration and haven't been executed yet.

Since:
1.6.2


getCommandline

protected CommandlineJava getCommandline()

Since:
Ant 1.6.2


getDefaultOutput

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

Returns:
default output stream for a formatter

Since:
Ant 1.3


getIndividualTests

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

Returns:
enumeration over individual tests

Since:
Ant 1.3


getOutput

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

Parameters:
fe - formatter element
test - one JUnit test

Returns:
file reference

Since:
Ant 1.3


handleErrorFlush

public void handleErrorFlush(String output)
Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
Overrides:
handleErrorFlush in interface Task

Parameters:
output - coming from System.err

Since:
Ant 1.5.2


handleErrorOutput

public void handleErrorOutput(String output)
Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
Overrides:
handleErrorOutput in interface Task

Parameters:
output - output coming from System.err

Since:
Ant 1.5


handleFlush

protected void handleFlush(String output)
Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
Overrides:
handleFlush in interface Task

Parameters:
output - output coming from System.out

Since:
Ant 1.5.2


handleInput

protected int handleInput(byte[] buffer,
                          int offset,
                          int length)
            throws IOException
Overrides:
handleInput in interface Task

Since:
Ant 1.6

See Also:
Task.handleInput(byte[],int,int)


handleOutput

protected void handleOutput(String output)
Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
Overrides:
handleOutput in interface Task

Parameters:
output - output coming from System.out

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 interface Task

Since:
Ant 1.4


setDir

public void setDir(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)


setErrorProperty

public void setErrorProperty(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


setFailureProperty

public void setFailureProperty(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


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


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(Integer)


setForkMode

public void setForkMode(JUnitTask.ForkMode mode)
Set the behavior when fork fork has been enabled.

Possible values are "once", "perTest" and "perBatch". If set to "once", only a single Java VM will be forked for all tests, with "perTest" (the default) each test will run in a fresh Java VM and "perBatch" will run all tests from the same <batchtest> in the same Java VM.

This attribute will be ignored if tests run in the same VM as Ant.

Only tests with the same configuration of haltonerror, haltonfailure, errorproperty, failureproperty and filtertrace can share a forked Java VM, so even if you set the value to "once", Ant may need to fork mutliple VMs.

Since:
Ant 1.6.2


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


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


setIncludeantruntime

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

Parameters:
b - include ant run time yes or no

Since:
Ant 1.5


setJvm

public void setJvm(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)


setMaxmemory

public void setMaxmemory(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


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.

Parameters:
newenv - boolean indicating if setting a new environment is wished

Since:
Ant 1.5


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


setReloading

public void setReloading(boolean value)
If true, force ant to re-classload all classes for each JUnit TestCase

Parameters:
value - force class reloading for each test case


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.

Parameters:
showOutput - if true, send output to Ant's logging system too

Since:
Ant 1.5


setTempdir

public void setTempdir(File tmpDir)
Where Ant should place temporary files.

Parameters:
tmpDir - location where temporary files should go to

Since:
Ant 1.6


setTimeout

public void setTimeout(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)


Copyright B) 2000-2005 Apache Software Foundation. All Rights Reserved.