org.apache.tools.ant.taskdefs.optional.junit
public class JUnitTask extends Task
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.
<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
Nested Class Summary | |
---|---|
static class | JUnitTask.ForkMode
These are the different forking options |
static class | JUnitTask.SummaryAttribute
Print summary enumeration values. |
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)
Adds a system property that tests can access.
|
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(JUnitTest arg)
Run the tests. |
protected void | execute(List tests)
Execute a list of tests in a single forked Java VM. |
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.
null otherwise. |
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 {@link #setFork 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).
|
Throws: Exception under ??? circumstances
Since: Ant 1.2
Since: Ant 1.6.2
Parameters: asserts assertion set
Since: Ant 1.6
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
Parameters: sysp new environment variable to add
Since: Ant 1.6
Will be ignored if we are not forking a new VM.
Parameters: var environment variable to be added
Since: Ant 1.5
Parameters: fe formatter element
Since: Ant 1.2
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
Parameters: sysp set of properties to be added
Since: Ant 1.6
Returns: enumeration
Since: Ant 1.3
Returns: a new instance of a batch test.
Since: Ant 1.2
Returns: reference to the bootclasspath in the embedded java command line
Since: Ant 1.6
Returns: reference to the classpath in the embedded java command line
Since: Ant 1.2
Returns: create a new JVM argument so that any argument can be passed to the JVM.
Since: Ant 1.2
Returns: .
Since: Ant 1.6
Returns: null if there is a timeout value, otherwise the watchdog instance.
Throws: BuildException under unspecified circumstances
Since: Ant 1.2
Throws: BuildException in case of test failures or errors
Since: Ant 1.2
Parameters: arg one JunitTest
Throws: BuildException in case of test failures or errors
Since: 1.6.2
Since: Ant 1.6.2
Returns: default output stream for a formatter
Since: Ant 1.3
Returns: enumeration over individual tests
Since: Ant 1.3
Parameters: fe formatter element test one JUnit test
Returns: file reference
Since: Ant 1.3
Parameters: output coming from System.err
Since: Ant 1.5.2
Parameters: output output coming from System.err
Since: Ant 1.5
Parameters: output output coming from System.out
Since: Ant 1.5.2
Since: Ant 1.6
See Also: (byte[], int, int)
Parameters: output output coming from System.out
Since: Ant 1.5
Since: Ant 1.4
Parameters: dir the directory to invoke the JVM from.
Since: Ant 1.2
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
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
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
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: JUnitTask
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
Parameters: value true if it should halt, otherwise false
Since: Ant 1.2
Parameters: value true if it should halt, otherwise false
Since: Ant 1.2
Parameters: b include ant run time yes or no
Since: Ant 1.5
Parameters: value the new VM to use instead of java
Since: Ant 1.2
Parameters: max the value as defined by -mx or -Xmx in the java command line options.
Since: Ant 1.2
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
Parameters: value true to print a summary, withOutAndErr to include the test's output as well, false otherwise.
Since: Ant 1.2
Parameters: value force class reloading for each test case
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
Parameters: tmpDir location where temporary files should go to
Since: Ant 1.6
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