Package 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

- All Implemented Interfaces:
    `java.lang.Cloneable`

      public class JUnitTask
      extends Task

  Runs JUnit tests.

  JUnit is a framework to create unit tests. It has been initially created by Erich Gamma and Kent Beck. JUnit can be found at https://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" value="${build.tests.value}"/>
           <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

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `JUnitTask.ForkMode` | These are the different forking options
    `protected static class` | `JUnitTask.JUnitLogOutputStream` | A stream handler for handling the junit task.
    `protected static class` | `JUnitTask.JUnitLogStreamHandler` | A log stream handler for junit.
    `static class` | `JUnitTask.SummaryAttribute` | Print summary enumeration values.
    `protected static class` | `JUnitTask.TestResultHolder` | A value class that contains the result of a test.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `ENABLE_TESTLISTENER_EVENTS` | Name of magic property that enables test listener events.
    `static java.lang.String` | `TESTLISTENER_PREFIX` |

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `JUnitTask()` | Creates a new JUnitRunner and enables fork of a new Java VM.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `actOnTestResult​(int exitValue, boolean wasKilled, JUnitTest test, java.lang.String name)` | Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occurred or sets a property.
    `protected void` | `actOnTestResult​(JUnitTask.TestResultHolder result, JUnitTest test, java.lang.String name)` | Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occurred or sets a property.
    `void` | `addAssertions​(Assertions asserts)` | Assertions to enable in this program (if fork=true)
    `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` | `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 java.util.Enumeration<BaseTest>` | `allTests()` | return an enumeration listing each test, then each batchtest
    `protected void` | `cleanup()` | Removes resources.
    `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.
    `Path` | `createModulepath()` | Add a path to the modulepath.
    `Permissions` | `createPermissions()` | Sets the permissions for the application run inside the same JVM.
    `Path` | `createUpgrademodulepath()` | Add a path to the upgrademodulepath.
    `protected ExecuteWatchdog` | `createWatchdog()` |
    `void` | `execute()` | Runs the testcase.
    `protected void` | `execute​(java.util.List<JUnitTest> testList)` | Execute a list of tests in a single forked Java VM.
    `protected void` | `execute​(java.util.List<JUnitTest> testList, int thread)` | Execute a list of tests in a single forked Java VM.
    `protected void` | `execute​(JUnitTest arg)` | Run the tests.
    `protected void` | `execute​(JUnitTest arg, int thread)` | Run the tests.
    `protected java.util.Collection<java.util.List<JUnitTest>>` | `executeOrQueue​(java.util.Enumeration<JUnitTest> 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()` | Get the command line used to run the tests.
    `protected java.io.OutputStream` | `getDefaultOutput()` | Get the default output for a formatter.
    `boolean` | `getEnableTestListenerEvents()` | Whether test listener events shall be generated.
    `protected java.util.Enumeration<JUnitTest>` | `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 output)` | Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
    `void` | `handleErrorOutput​(java.lang.String output)` | Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
    `protected void` | `handleFlush​(java.lang.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)` | Handle an input request by this task.
    `protected void` | `handleOutput​(java.lang.String output)` | Pass output sent to System.out to the TestRunner so it can collect it 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` | `setCloneVm​(boolean cloneVm)` | If set, system properties will be copied to the cloned VM - as well as the bootclasspath unless you have explicitly specified a bootclasspath.
    `void` | `setDir​(java.io.File dir)` | The directory to invoke the VM in.
    `void` | `setEnableTestListenerEvents​(boolean b)` | Whether test listener events shall be generated.
    `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` | `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​(java.lang.String value)` | The command used to invoke the Java Virtual Machine, default is 'java'.
    `void` | `setLogFailedTests​(boolean logFailedTests)` | If true, write a single "FAILED" line for failed tests to Ant's log system.
    `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` | `setOutputToFormatters​(boolean outputToFormatters)` | If true, send any output generated by tests to the formatters.
    `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​(java.io.File tmpDir)` | Where Ant should place temporary files.
    `void` | `setThreads​(int threads)` | Set the number of test threads to be used for parallel test execution.
    `void` | `setTimeout​(java.lang.Integer value)` | Set the timeout value (in milliseconds).
    `protected void` | `setupJUnitDelegate()` | Sets up the delegate that will actually run the tests.

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

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

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

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TESTLISTENER_PREFIX

          public static final java.lang.String TESTLISTENER_PREFIX

      Since:
        Ant 1.7
      See Also:
        Constant Field Values

    - #### ENABLE_TESTLISTENER_EVENTS

          public static final java.lang.String ENABLE_TESTLISTENER_EVENTS

      Name of magic property that enables test listener events.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### JUnitTask

          public JUnitTask()
                    throws java.lang.Exception

      Creates a new JUnitRunner and enables fork of a new Java VM.
      Throws:
        `java.lang.Exception` - never
      Since:
        Ant 1.2

  - ### Method Detail

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

    - #### 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 overridden 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 overridden 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)`

    - #### 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 multiple VMs.

      Parameters:
        `mode` - the mode to use.
      Since:
        Ant 1.6.2

    - #### setThreads

          public void setThreads​(int threads)

      Set the number of test threads to be used for parallel test execution. The default is 1, which is the same behavior as before parallel test execution was possible.

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

      Parameters:
        `threads` - int
      Since:
        Ant 1.9.4

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

          @Deprecated
          public void addSysproperty​(Environment.Variable sysp)

      Deprecated.
      since Ant 1.6
      Adds a system property that tests can access. This might be useful to transfer Ant properties to the testcases when JVM forking is not enabled.
      Parameters:
        `sysp` - environment variable to add
      Since:
        Ant 1.3

    - #### addConfiguredSysproperty

          public void addConfiguredSysproperty​(Environment.Variable sysp)

      Adds a system property that tests can access. This might be useful to transfer Ant properties to the testcases when JVM forking is not enabled.
      Parameters:
        `sysp` - new environment variable to add
      Since:
        Ant 1.6

    - #### 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 transfer Ant properties to the testcases when JVM forking is not enabled.

      Parameters:
        `sysp` - set of properties to be added
      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

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

    - #### createModulepath

          public Path createModulepath()

      Add a path to the modulepath.
      Returns:
        created modulepath.
      Since:
        1.9.8

    - #### createUpgrademodulepath

          public Path createUpgrademodulepath()

      Add a path to the upgrademodulepath.
      Returns:
        created upgrademodulepath.
      Since:
        1.9.8

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

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

    - #### 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.
      Parameters:
        `fe` - formatter element
      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

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

    - #### setOutputToFormatters

          public void setOutputToFormatters​(boolean outputToFormatters)

      If true, send any output generated by tests to the formatters.
      Parameters:
        `outputToFormatters` - if true, send output to formatters (Default is true).
      Since:
        Ant 1.7.0

    - #### setLogFailedTests

          public void setLogFailedTests​(boolean logFailedTests)

      If true, write a single "FAILED" line for failed tests to Ant's log system.
      Parameters:
        `logFailedTests` - boolean
      Since:
        Ant 1.8.0

    - #### addAssertions

          public void addAssertions​(Assertions asserts)

      Assertions to enable in this program (if fork=true)
      Parameters:
        `asserts` - assertion set
      Since:
        Ant 1.6

    - #### createPermissions

          public Permissions createPermissions()

      Sets the permissions for the application run inside the same JVM.
      Returns:
        Permissions
      Since:
        Ant 1.6

    - #### setCloneVm

          public void setCloneVm​(boolean cloneVm)

      If set, system properties will be copied to the cloned VM - as well as the bootclasspath unless you have explicitly specified a bootclasspath.

      Doesn't have any effect unless fork is true.

      Parameters:
        `cloneVm` - a `boolean` value.
      Since:
        Ant 1.7

    - #### setTempdir

          public void setTempdir​(java.io.File tmpDir)

      Where Ant should place temporary files.
      Parameters:
        `tmpDir` - location where temporary files should go to
      Since:
        Ant 1.6

    - #### setEnableTestListenerEvents

          public void setEnableTestListenerEvents​(boolean b)

      Whether test listener events shall be generated.

      Defaults to false.

      This value will be overridden by the magic property ant.junit.enabletestlistenerevents if it has been set.

      Parameters:
        `b` - boolean
      Since:
        Ant 1.8.2

    - #### getEnableTestListenerEvents

          public boolean getEnableTestListenerEvents()

      Whether test listener events shall be generated.
      Returns:
        boolean
      Since:
        Ant 1.8.2

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

    - #### setupJUnitDelegate

          protected void setupJUnitDelegate()

      Sets up the delegate that will actually run the tests.

      Will be invoked implicitly once the delegate is needed.

      Since:
        Ant 1.7.1

    - #### execute

          public void execute()
                       throws BuildException

      Runs the testcase.
      Overrides:
        `execute` in class `Task`
      Throws:
        `BuildException` - in case of test failures or errors
      Since:
        Ant 1.2

    - #### execute

          protected void execute​(JUnitTest arg,
                                 int thread)
                          throws BuildException

      Run the tests.
      Parameters:
        `arg` - one JUnitTest
        `thread` - Identifies which thread is test running in (0 for single-threaded runs)
      Throws:
        `BuildException` - in case of test failures or errors

    - #### execute

          protected void execute​(JUnitTest arg)
                          throws BuildException

      Run the tests.
      Parameters:
        `arg` - one JUnitTest
      Throws:
        `BuildException` - in case of test failures or errors

    - #### execute

          protected void execute​(java.util.List<JUnitTest> testList,
                                 int thread)
                          throws BuildException

      Execute a list of tests in a single forked Java VM.
      Parameters:
        `testList` - the list of tests to execute.
        `thread` - Identifies which thread is test running in (0 for single-threaded runs)
      Throws:
        `BuildException` - on error.

    - #### execute

          protected void execute​(java.util.List<JUnitTest> testList)
                          throws BuildException

      Execute a list of tests in a single forked Java VM.
      Parameters:
        `testList` - the list of tests to execute.
      Throws:
        `BuildException` - on error.

    - #### handleOutput

          protected void handleOutput​(java.lang.String output)

      Pass output sent to System.out to the TestRunner so it can collect it for the formatters.
      Overrides:
        `handleOutput` in class `Task`
      Parameters:
        `output` - output coming from System.out
      Since:
        Ant 1.5

    - #### handleInput

          protected int handleInput​(byte[] buffer,
                                    int offset,
                                    int length)
                             throws java.io.IOException

      Handle an input request by this task.
      Overrides:
        `handleInput` in class `Task`
      Parameters:
        `buffer` - the buffer into which data is to be read.
        `offset` - the offset into the buffer at which data is stored.
        `length` - the amount of data to read.
      Returns:
        the number of bytes read.
      Throws:
        `java.io.IOException` - if the data cannot be read.
      Since:
        Ant 1.6
      See Also:
        `This implementation delegates to a runner if it present.`

    - #### handleFlush

          protected void handleFlush​(java.lang.String output)

      Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
      Overrides:
        `handleFlush` in class `Task`
      Parameters:
        `output` - output coming from System.out
      Since:
        Ant 1.5.2

    - #### handleErrorOutput

          public void handleErrorOutput​(java.lang.String output)

      Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
      Overrides:
        `handleErrorOutput` in class `Task`
      Parameters:
        `output` - output coming from System.err
      Since:
        Ant 1.5

    - #### handleErrorFlush

          public void handleErrorFlush​(java.lang.String output)

      Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
      Overrides:
        `handleErrorFlush` in class `Task`
      Parameters:
        `output` - coming from System.err
      Since:
        Ant 1.5.2

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

    - #### getDefaultOutput

          protected java.io.OutputStream getDefaultOutput()

      Get the default output for a formatter.
      Returns:
        default output stream for a formatter
      Since:
        Ant 1.3

    - #### getIndividualTests

          protected java.util.Enumeration<JUnitTest> 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

    - #### allTests

          protected java.util.Enumeration<BaseTest> allTests()

      return an enumeration listing each test, then each batchtest
      Returns:
        enumeration
      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.
      Parameters:
        `fe` - formatter element
        `test` - one JUnit test
      Returns:
        file reference
      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.

      Parameters:
        `resource` - resource that one wants to lookup
      Since:
        Ant 1.4

    - #### cleanup

          protected void cleanup()

      Removes resources.

      Is invoked in `execute`. Subclasses that don't invoke execute should invoke this method in a finally block.

      Since:
        Ant 1.7.1

    - #### getCommandline

          protected CommandlineJava getCommandline()

      Get the command line used to run the tests.
      Returns:
        the command line.
      Since:
        Ant 1.6.2

    - #### executeOrQueue

          protected java.util.Collection<java.util.List<JUnitTest>> executeOrQueue​(java.util.Enumeration<JUnitTest> 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.
      Parameters:
        `testList` - the list of tests to be executed or queued.
        `runIndividual` - if true execute each test individually.
      Returns:
        a list of tasks to be executed.
      Since:
        1.6.2

    - #### actOnTestResult

          protected void actOnTestResult​(int exitValue,
                                         boolean wasKilled,
                                         JUnitTest test,
                                         java.lang.String name)

      Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occurred or sets a property.
      Parameters:
        `exitValue` - the exitValue of the test.
        `wasKilled` - if true, the test had been killed.
        `test` - the test in question.
        `name` - the name of the test.
      Since:
        Ant 1.6.2

    - #### actOnTestResult

          protected void actOnTestResult​(JUnitTask.TestResultHolder result,
                                         JUnitTest test,
                                         java.lang.String name)

      Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occurred or sets a property.
      Parameters:
        `result` - the result of the test.
        `test` - the test in question.
        `name` - the name of the test.
      Since:
        Ant 1.7