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

  • Field Details

    • TESTLISTENER_PREFIX

      public static final String TESTLISTENER_PREFIX
      Since:
      Ant 1.7
      See Also:

    • ENABLE_TESTLISTENER_EVENTS

      public static final String ENABLE_TESTLISTENER_EVENTS
      Name of magic property that enables test listener events.
      See Also:

  • Constructor Details

    • JUnitTask

      public JUnitTask() throws Exception
      Creates a new JUnitRunner and enables fork of a new Java VM.
      Throws:
      Exception - never
      Since:
      Ant 1.2

  • Method Details

    • 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 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(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:

    • 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:

    • 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 Commandline.Argument createJvmarg()
      Adds a JVM argument; ignored if not forking.
      Returns:
      create a new JVM arg