## 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 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
Version:
  $Revision: 1.44.2.7 $
Author:
  Thomas Haas, Stefan Bodewig, Stephane Bailliez, Gerrit Riessen, Erik Hatcher, Martijn Kruithof>
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.
`void` `handleErrorFlush(java.lang.String line)` Pass output sent to System.err to the TestRunner so it can collect ot for the formatters.
`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` `handleFlush(java.lang.String line)` Pass output sent to System.out 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

### handleFlush

    protected void handleFlush(java.lang.String line)

  Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.

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

### handleErrorOutput

    public 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

### handleErrorFlush

    public void handleErrorFlush(java.lang.String line)

  Pass output sent to System.err to the TestRunner so it can collect ot for the formatters.

  Overrides:
    `handleErrorFlush` in class `Task`
  Parameters:
    `line` - The error line to log. Should not be `null`.
  Since:
    Ant 1.5.2

### 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

Copyright © 2000-2003 Apache Software Foundation. All Rights Reserved.