Class JUnitTask

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
de.hybris.ant.taskdefs.yunit.JUnitTask
All Implemented Interfaces:
Cloneable

public class JUnitTask extends org.apache.tools.ant.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 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:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    These are the different forking options
    protected static class 
    A stream handler for handling the junit task.
    protected static class 
    A log stream handler for junit.
    static class 
    Print summary enumeration values.
    protected class 
    A value class that contains the result of a test.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
     

    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
    Creates a new JUnitRunner and enables fork of a new Java VM.
  • Method Summary

    Modifier and Type
    Method
    Description
    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 occurred or sets a property.
    protected void
    Logs information about failed tests, potentially stops processing (by throwing a BuildException) if a failure/error occurred or sets a property.
    void
    addAssertions(org.apache.tools.ant.types.Assertions asserts)
    Assertions to enable in this program (if fork=true)
    protected void
    Search for the given resource and add the directory or archive that contains it to the classpath.
    void
    addConfiguredSysproperty(org.apache.tools.ant.types.Environment.Variable sysp)
    Adds a system property that tests can access.
    void
    addEnv(org.apache.tools.ant.types.Environment.Variable var)
    Adds an environment variable; used when forking.
    void
    Add a new formatter to all tests of this task.
    void
    addSyspropertyset(org.apache.tools.ant.types.PropertySet sysp)
    Adds a set of properties that will be used as system properties that tests can access.
    void
    Add a new single testcase.
    protected Enumeration
    return an enumeration listing each test, then each batchtest
    protected void
    Removes resources.
    Adds a set of tests based on pattern matching.
    org.apache.tools.ant.types.Path
    Adds a path to the bootclasspath.
    org.apache.tools.ant.types.Path
    Adds path to classpath used for tests.
    org.apache.tools.ant.types.Commandline.Argument
    Adds a JVM argument; ignored if not forking.
    org.apache.tools.ant.types.Permissions
    Sets the permissions for the application run inside the same JVM.
    protected org.apache.tools.ant.taskdefs.ExecuteWatchdog
     
    void
    Runs the testcase.
    protected void
    Run the tests.
    protected void
    execute(List testList)
    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 org.apache.tools.ant.types.CommandlineJava
    Get the command line used to run the tests.
    protected OutputStream
    Get the default output for a formatter.
    protected Enumeration
    Merge all individual tests from the batchtest with all individual tests and return an enumeration over all JUnitTest.
    protected File
    If the formatter sends output to a file, return that file.
    void
    Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
    void
    Pass output sent to System.err to the TestRunner so it can collect it for the formatters.
    protected void
    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
    Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
    void
    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
     
    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 bootclaspath.
    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
    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
    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
    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
    setPlatformHome(String platformhome)
     
    void
    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
    setSuppressJunitTenant(boolean suppressJunitTenant)
    If true, Junit Tenant wil not be started for test execution.
    void
    setTempdir(File tmpDir)
    Where Ant should place temporary files.
    void
    Set the timeout value (in milliseconds).
    void
    setToDir(File todir)
     
    protected void
    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 Details

  • Constructor Details

    • JUnitTask

      public JUnitTask() throws Exception
      Creates a new JUnitRunner and enables fork of a new Java VM.
      Throws:
      Exception - under ??? circumstances
      Since:
      Ant 1.2
  • Method Details

    • setPlatformHome

      public void setPlatformHome(String platformhome)
    • setAdditionalClasspath

      public void setAdditionalClasspath(String classpath)
    • setToDir

      public void setToDir(File todir)
    • 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(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(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:
    • 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.

      Parameters:
      mode - the mode to use.
      Since:
      Ant 1.6.2
    • setSuppressJunitTenant

      public void setSuppressJunitTenant(boolean suppressJunitTenant)
      If true, Junit Tenant wil not be started for test execution. Might be useful especially in case of webtests
      Parameters:
      suppressJunitTenant - true if Junit tenant should not be started, otherwise false
    • 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:
    • 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:
    • 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
    • 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:
    • createJvmarg

      public org.apache.tools.ant.types.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:
    • 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:
    • addConfiguredSysproperty

      public void addConfiguredSysproperty(org.apache.tools.ant.types.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
    • addSyspropertyset

      public void addSyspropertyset(org.apache.tools.ant.types.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
    • createClasspath

      public org.apache.tools.ant.types.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 org.apache.tools.ant.types.Path createBootclasspath()
      Adds a path to the bootclasspath.
      Returns:
      reference to the bootclasspath in the embedded java command line
      Since:
      Ant 1.6
    • addEnv

      public void addEnv(org.apache.tools.ant.types.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:
    • 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:
    • 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
    • addAssertions

      public void addAssertions(org.apache.tools.ant.types.Assertions asserts)
      Assertions to enable in this program (if fork=true)
      Parameters:
      asserts - assertion set
      Since:
      Ant 1.6
    • createPermissions

      public org.apache.tools.ant.types.Permissions createPermissions()
      Sets the permissions for the application run inside the same JVM.
      Returns:
      .
      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 bootclaspath.

      Doesn't have any effect unless fork is true.

      Parameters:
      cloneVm - a boolean value.
      Since:
      Ant 1.7
    • 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
    • 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 org.apache.tools.ant.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 org.apache.tools.ant.BuildException
      Runs the testcase.
      Overrides:
      execute in class org.apache.tools.ant.Task
      Throws:
      org.apache.tools.ant.BuildException - in case of test failures or errors
      Since:
      Ant 1.2
    • execute

      protected void execute(JUnitTest arg) throws org.apache.tools.ant.BuildException
      Run the tests.
      Parameters:
      arg - one JunitTest
      Throws:
      org.apache.tools.ant.BuildException - in case of test failures or errors
    • execute

      protected void execute(List testList) throws org.apache.tools.ant.BuildException
      Execute a list of tests in a single forked Java VM.
      Parameters:
      testList - the list of tests to execute.
      Throws:
      org.apache.tools.ant.BuildException - on error.
    • 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 class org.apache.tools.ant.Task
      Parameters:
      output - output coming from System.out
      Since:
      Ant 1.5
    • handleInput

      protected int handleInput(byte[] buffer, int offset, int length) throws IOException
      Handle an input request by this task.
      Overrides:
      handleInput in class org.apache.tools.ant.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:
      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(String output)
      Pass output sent to System.out to the TestRunner so it can collect ot for the formatters.
      Overrides:
      handleFlush in class org.apache.tools.ant.Task
      Parameters:
      output - output coming from System.out
      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 class org.apache.tools.ant.Task
      Parameters:
      output - output coming from System.err
      Since:
      Ant 1.5
    • 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 class org.apache.tools.ant.Task
      Parameters:
      output - coming from System.err
      Since:
      Ant 1.5.2
    • createWatchdog

      protected org.apache.tools.ant.taskdefs.ExecuteWatchdog createWatchdog() throws org.apache.tools.ant.BuildException
      Returns:
      null if there is a timeout value, otherwise the watchdog instance.
      Throws:
      org.apache.tools.ant.BuildException - under unspecified circumstances
      Since:
      Ant 1.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
    • allTests

      protected Enumeration allTests()
      return an enumeration listing each test, then each batchtest
      Returns:
      enumeration
      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
    • 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
    • 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 org.apache.tools.ant.types.CommandlineJava getCommandline()
      Get the command line used to run the tests.
      Returns:
      the command line.
      Since:
      Ant 1.6.2
    • 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.
      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, 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, 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