Class JUnit4

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
com.carrotsearch.ant.tasks.junit4.JUnit4
All Implemented Interfaces:
Cloneable
public class JUnit4 extends org.apache.tools.ant.Task
An ANT task to run JUnit4 tests. Differences (benefits?) compared to ANT's default JUnit task:
  • Built-in parallel test execution support (spawns multiple JVMs to avoid test interactions).
  • Randomization of the order of test suites within a single JVM.
  • Aggregates and synchronizes test events from executors. All reports run on the task's JVM (not on the test JVM).
  • Fully configurable reporting via listeners (console, ANT-compliant XML, JSON). Report listeners use Google Guava's EventBus and receive full information about tests' execution (including skipped, assumption-skipped tests, streamlined output and error stream chunks, etc.).
  • JUnit 4.10+ is required both for the task and for the tests classpath. Older versions will cause build failure.
  • Integration with RandomizedRunner (randomization seed is passed to children JVMs).

  • Field Details

  • Constructor Details

    • JUnit4

      public JUnit4()

  • Method Details

    • setJvmOutputAction

      public void setJvmOutputAction(String jvmOutputActions)
      What should be done on unexpected JVM output? JVM may write directly to the original descriptors, bypassing redirections of System.out and System.err. Typically, these messages will be important and should fail the build (permgen space exceeded, compiler errors, crash dumps). However, certain legitimate logs (gc activity, class loading logs) are also printed to these streams so sometimes the output can be ignored.

      Allowed values (any comma-delimited combination of): JUnit4.JvmOutputAction constants.

    • setSysouts

      public void setSysouts(boolean sysouts)
      If set to true, any sysout and syserr calls will be written to original output and error streams (and in effect will appear as "jvm output". By default sysout and syserrs are captured and proxied to the event stream to be synchronized with other test events but occasionally one may want to synchronize them with direct JVM output (to synchronize with compiler output or GC output for example).

    • setDebugStream

      public void setDebugStream(boolean debugStream)
      Enables a debug stream from each forked JVM. This will create an additional file next to each events file. For debugging the framework only, not a general-purpose setting.

    • setUniqueSuiteNames

      public void setUniqueSuiteNames(boolean uniqueSuiteNames)
      Allow or disallow duplicate suite names in resource collections. By default this option is true because certain ANT-compatible report types (like XML reports) will have a problem with duplicate suite names (will overwrite files).

    • isUniqueSuiteNames

      public boolean isUniqueSuiteNames()
      See Also:

    • setDynamicAssignmentRatio

      public void setDynamicAssignmentRatio(float ratio)
      Specifies the ratio of suites moved to dynamic assignment list. A dynamic assignment list dispatches suites to the first idle slave JVM. Theoretically this is an optimal strategy, but it is usually better to have some static assignments to avoid communication costs.

      A ratio of 0 means only static assignments are used. A ratio of 1 means only dynamic assignments are used.

      The list of dynamic assignments is sorted by decreasing cost (always) and is inherently prone to race conditions in distributing suites. Should there be an error based on suite-dependency it will not be directly repeatable. In such case use the per-slave-jvm list of suites file dumped to disk for each slave JVM. (see setLeaveTemporary(boolean)).

    • setParallelism

      public void setParallelism(String parallelism)
      The number of parallel slaves. Can be set to a constant "max" for the number of cores returned from Runtime.availableProcessors() or "auto" for sensible defaults depending on the number of cores. The default is a single subprocess.

      Note that this setting forks physical JVM processes so it multiplies the requirements for heap memory, IO, etc.

    • setFailureProperty

      public void setFailureProperty(String failureProperty)
      Property to set to "true" if there is a failure in a test.

    • setNewEnvironment

      public void setNewEnvironment(boolean v)
      Do not propagate the old environment when new environment variables are specified.

    • setSeed

      public void setSeed(String randomSeed)
      Initial random seed used for shuffling test suites and other sources of pseudo-randomness. If not set, any random value is set.

      The seed's format is compatible with RandomizedRunner so that seed can be fixed for suites and methods alike.

    • setPrefix

      public void setPrefix(String prefix)
      Initializes custom prefix for all junit4 properties. This must be consistent across all junit4 invocations if done from the same classpath. Use only when REALLY needed.

    • getSeed

      public String getSeed()
      See Also:

    • setShuffleOnSlave

      public void setShuffleOnSlave(boolean shuffle)
      Predictably shuffle tests order after balancing. This will help in spreading lighter and heavier tests over a single slave's execution timeline while still keeping the same tests order depending on the seed.

    • setProject

      public void setProject(org.apache.tools.ant.Project project)
      Overrides:
      setProject in class org.apache.tools.ant.ProjectComponent

    • setPrintSummary

      public void setPrintSummary(boolean printSummary)
      Prints the summary of all executed, ignored etc. tests at the end.

    • setHaltOnFailure

      public void setHaltOnFailure(boolean haltOnFailure)
      Stop the build process if there were failures or errors during test execution.

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

    • setLeaveTemporary

      public void setLeaveTemporary(boolean leaveTemporary)
      Set to true to leave temporary files for diagnostics.

    • createJvmarg

      public org.apache.tools.ant.types.Commandline.Argument createJvmarg()
      Add an additional argument to any forked JVM.

    • setDir

      public void setDir(File dir)
      The directory to invoke forked VMs in.

    • setTempDir

      public void setTempDir(File tempDir)
      The directory to store temporary files in.

    • setIfNoTests

      public void setIfNoTests(String value)
      What to do when no tests were executed (all tests were ignored)?
      See Also:

    • addConfiguredSysproperty

      public void addConfiguredSysproperty(JUnit4.ExtendedVariable sysp)
      Adds a system property to any forked JVM.

    • addConfiguredSyspropertyset

      public void addConfiguredSyspropertyset(JUnit4.ExtendedPropertySet 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.

    • setJvm

      public void setJvm(String jvm)
      The command used to invoke the Java Virtual Machine, default is 'java'. The command is resolved by java.lang.Runtime.exec().

    • setIsolateWorkingDirectories

      public void setIsolateWorkingDirectories(boolean isolateWorkingDirectories)
      If set to true each slave JVM gets a separate working directory under whatever is set in setDir(File). The directory naming for each slave follows: "Snum", where num is slave's number. Directories are created automatically and removed unless setLeaveTemporary(boolean) is set to true.

    • setOnNonEmptyWorkDirectory

      public void setOnNonEmptyWorkDirectory(String value)
      Determines the behavior on detecting non-empty existing current working directory for a forked JVM, before the tests commence. This action is performed only if work directory isolation is set to true (see setIsolateWorkingDirectories(boolean)).

    • addEnv

      public void addEnv(JUnit4.ExtendedVariable var)
      Adds an environment variable; used when forking.

    • addFileSet

      public void addFileSet(org.apache.tools.ant.types.FileSet fs)
      Adds a set of tests based on pattern matching.

    • add

      public void add(org.apache.tools.ant.types.ResourceCollection rc)
      Adds a set of tests based on pattern matching.

    • createListeners

      public ListenersList createListeners()
      Creates a new list of listeners.

    • addAssertions

      public void addAssertions(org.apache.tools.ant.types.Assertions asserts)
      Add assertions to tests execution.

    • createBalancers

      public BalancersList createBalancers()
      Creates a new list of balancers.

    • 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

    • 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

    • setFork

      public void setFork(boolean fork)

    • setForkmode

      public void setForkmode(String forkMode)

    • setHaltOnError

      public void setHaltOnError(boolean haltOnError)

    • setFiltertrace

      public void setFiltertrace(boolean filterTrace)

    • setTimeout

      public void setTimeout(String v)

    • setIncludeantruntime

      public void setIncludeantruntime(String v)

    • setShowoutput

      public void setShowoutput(String v)

    • setOutputtoformatters

      public void setOutputtoformatters(String v)

    • setReloading

      public void setReloading(String v)

    • setClonevm

      public void setClonevm(String v)

    • setErrorproperty

      public void setErrorproperty(String v)

    • setLogfailedtests

      public void setLogfailedtests(String v)

    • setEnableTestListenerEvents

      public void setEnableTestListenerEvents(String v)

    • createFormatter

      public Object createFormatter()

    • createTest

      public Object createTest()

    • createBatchtest

      public Object createBatchtest()

    • warnUnsupported

      private void warnUnsupported(String attName)

    • setHeartbeat

      public void setHeartbeat(long heartbeat)
      Sets the heartbeat used to detect inactive/ hung forked tests (JVMs) to the given number of seconds. The heartbeat detects no-event intervals and will report them to listeners. Notably, text report report will emit heartbeat information (to a file or console).

      Setting the heartbeat to zero means no detection.

    • setStatsPropertyPrefix

      public void setStatsPropertyPrefix(String statsPropertyPrefix)
      Sets the property prefix to which test statistics are saved.

    • execute

      public void execute() throws org.apache.tools.ant.BuildException
      Overrides:
      execute in class org.apache.tools.ant.Task
      Throws:
      org.apache.tools.ant.BuildException

    • listFiles

      private static List<String> listFiles(Path f) throws IOException
      Throws:
      IOException

    • validateArguments

      private void validateArguments() throws org.apache.tools.ant.BuildException
      Validate arguments.
      Throws:
      org.apache.tools.ant.BuildException

    • validateJUnit4

      private void validateJUnit4() throws org.apache.tools.ant.BuildException
      Validate JUnit4 presence in a concrete version.
      Throws:
      org.apache.tools.ant.BuildException

    • loadBalanceSuites

      private List<String> loadBalanceSuites(List<ForkedJvmInfo> jvmInfo, TestsCollection testsCollection, List<SuiteBalancer> balancers)
      Perform load balancing of the set of suites. Sets ForkedJvmInfo.testSuites to suites preassigned to a given slave and returns a pool of suites that should be load-balanced dynamically based on job stealing.

    • sortAndSplitReplicated

      private Map<Boolean, List<String>> sortAndSplitReplicated(List<TestClass> testClasses)

    • masterSeed

      private long masterSeed()
      Return the master seed of getSeed().

    • resolveFiles

      private org.apache.tools.ant.types.Path resolveFiles(org.apache.tools.ant.types.Path path)
      Resolve all files from a given path and simplify its definition.

    • determineForkedJvmCount

      private int determineForkedJvmCount(TestsCollection testCollection)
      Determine how many forked JVMs to use.

    • executeSlave

      private void executeSlave(ForkedJvmInfo slave, com.google.common.eventbus.EventBus aggregatedBus) throws Exception
      Attach listeners and execute a slave process.
      Throws:
      Exception

    • checkJvmOutput

      private void checkJvmOutput(com.google.common.eventbus.EventBus aggregatedBus, Path file, ForkedJvmInfo forked, String fileName) throws IOException
      Throws:
      IOException

    • tempFile

      private Path tempFile(String uniqueSeed, String base, String suffix, Path tempDir) throws IOException
      Throws:
      IOException

    • escapeAndJoin

      private String escapeAndJoin(String[] commandline)
      Try to provide an escaped, ready-to-use shell line to repeat a given command line.

    • forkProcess

      private org.apache.tools.ant.taskdefs.Execute forkProcess(ForkedJvmInfo slaveInfo, com.google.common.eventbus.EventBus eventBus, org.apache.tools.ant.types.CommandlineJava commandline, InputStream eventStream, OutputStream sysout, OutputStream syserr, RandomAccessFile streamsBuffer)
      Execute a slave process. Pump events to the given event bus.

    • getWorkingDirectory

      private Path getWorkingDirectory(ForkedJvmInfo jvmInfo) throws IOException
      Throws:
      IOException

    • getTempDir

      private Path getTempDir()
      Resolve temporary folder.

    • processTestResources

      private TestsCollection processTestResources()
      Process test resources. If there are any test resources that are _not_ class files, this will cause a build error.

    • getCommandline

      private org.apache.tools.ant.types.CommandlineJava getCommandline()
      Returns the slave VM command line.

    • addSlaveClasspath

      private org.apache.tools.ant.types.Path addSlaveClasspath()
      Adds a classpath source which contains the given resource. TODO: [GH-213] this is extremely ugly; separate the code required to run on the forked JVM into an isolated bundle and either create it on-demand (in temp. files location?) or locate it in classpath somehow (in a portable way).