com.carrotsearch.ant.tasks.junit4
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 Summary

static String	ANTLIB_RESOURCE_NAME Name of the antlib resource inside JUnit4 JAR.
static float	DEFAULT_DYNAMIC_ASSIGNMENT_RATIO Default value of setDynamicAssignmentRatio(float)
static boolean	DEFAULT_HALT_ON_FAILURE Default value of setHaltOnFailure(boolean).
static boolean	DEFAULT_ISOLATE_WORKING_DIRECTORIES Default value of setIsolateWorkingDirectories(boolean).
static String	DEFAULT_PARALLELISM Default value of setParallelism(java.lang.String).
static boolean	DEFAULT_PRINT_SUMMARY Default value of setPrintSummary(boolean).
static boolean	DEFAULT_SHUFFLE_ON_SLAVE Default value of setShuffleOnSlave(boolean).
static Object	PARALLELISM_AUTO
static String	PARALLELISM_MAX

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

JUnit4()

Method Summary

void	add(org.apache.tools.ant.types.ResourceCollection rc) Adds a set of tests based on pattern matching.
void	addAssertions(org.apache.tools.ant.types.Assertions asserts) Add assertions to tests execution.
void	addConfiguredSysproperty(org.apache.tools.ant.types.Environment.Variable sysp) Adds a system property to any forked JVM.
void	addEnv(org.apache.tools.ant.types.Environment.Variable var) Adds an environment variable; used when forking.
void	addFileSet(org.apache.tools.ant.types.FileSet fs) Adds a set of tests based on pattern matching.
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.
BalancersList	createBalancers() Creates a new list of balancers.
Object	createBatchtest()
org.apache.tools.ant.types.Path	createBootclasspath() Adds a path to the bootclasspath.
org.apache.tools.ant.types.Path	createClasspath() Adds path to classpath used for tests.
Object	createFormatter()
org.apache.tools.ant.types.Commandline.Argument	createJvmarg() Add an additional argument to any forked JVM.
ListenersList	createListeners() Creates a new list of listeners.
Object	createTest()
void	execute()
String	getSeed()
void	setClonevm(String v)
void	setDir(File dir) The directory to invoke forked VMs in.
void	setDynamicAssignmentRatio(float ratio) Specifies the ratio of suites moved to dynamic assignment list.
void	setEnableTestListenerEvents(String v)
void	setErrorproperty(String v)
void	setFailureProperty(String failureProperty) Property to set to "true" if there is a failure in a test.
void	setFiltertrace(boolean filterTrace)
void	setFork(boolean fork)
void	setForkmode(String forkMode)
void	setHaltOnError(boolean haltOnError)
void	setHaltOnFailure(boolean haltOnFailure) Stop the build process if there were failures or errors during test execution.
void	setIncludeantruntime(String v)
void	setIsolateWorkingDirectories(boolean isolateWorkingDirectories) If set to true each slave JVM gets a separate working directory under whatever is set in setDir(File).
void	setJvm(String jvm) The command used to invoke the Java Virtual Machine, default is 'java'.
void	setLeaveTemporary(boolean leaveTemporary) Set to true to leave temporary files for diagnostics.
void	setLogfailedtests(String v)
void	setMaxmemory(String max) Set the maximum memory to be used by all forked JVMs.
void	setNewEnvironment(boolean v) Do not propagate the old environment when new environment variables are specified.
void	setOutputtoformatters(String v)
void	setParallelism(String parallelism) The number of parallel slaves.
void	setPrefix(String prefix) Initializes custom prefix for all junit4 properties.
void	setPrintSummary(boolean printSummary) Prints the summary of all executed, ignored etc.
void	setProject(org.apache.tools.ant.Project project)
void	setReloading(String v)
void	setSeed(String randomSeed) Initial random seed used for shuffling test suites and other sources of pseudo-randomness.
void	setShowoutput(String v)
void	setShuffleOnSlave(boolean shuffle) Predictably shuffle tests order after balancing.
void	setTempDir(File tempDir) The directory to store temporary files in.
void	setTimeout(String v)

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

bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, 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

Methods inherited from class java.lang.Object

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

Field Detail

ANTLIB_RESOURCE_NAME

public static final String ANTLIB_RESOURCE_NAME

Name of the antlib resource inside JUnit4 JAR.

See Also:

Constant Field Values

PARALLELISM_AUTO

public static final Object PARALLELISM_AUTO

See Also:

setParallelism(String)

PARALLELISM_MAX

public static final String PARALLELISM_MAX

See Also:

setParallelism(String), Constant Field Values

DEFAULT_SHUFFLE_ON_SLAVE

public static final boolean DEFAULT_SHUFFLE_ON_SLAVE

Default value of setShuffleOnSlave(boolean).

See Also:

Constant Field Values

DEFAULT_PARALLELISM

public static final String DEFAULT_PARALLELISM

Default value of setParallelism(java.lang.String).

See Also:

Constant Field Values

DEFAULT_PRINT_SUMMARY

public static final boolean DEFAULT_PRINT_SUMMARY

Default value of setPrintSummary(boolean).

See Also:

Constant Field Values

DEFAULT_HALT_ON_FAILURE

public static final boolean DEFAULT_HALT_ON_FAILURE

Default value of setHaltOnFailure(boolean).

See Also:

Constant Field Values

DEFAULT_ISOLATE_WORKING_DIRECTORIES

public static final boolean DEFAULT_ISOLATE_WORKING_DIRECTORIES

Default value of setIsolateWorkingDirectories(boolean).

See Also:

Constant Field Values

DEFAULT_DYNAMIC_ASSIGNMENT_RATIO

public static final float DEFAULT_DYNAMIC_ASSIGNMENT_RATIO

Default value of setDynamicAssignmentRatio(float)

See Also:

Constant Field Values

Constructor Detail

JUnit4

public JUnit4()

Method Detail

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:

setSeed(String)

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.

addConfiguredSysproperty

public void addConfiguredSysproperty(org.apache.tools.ant.types.Environment.Variable sysp)

Adds a system property to any forked JVM.

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.

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.

addEnv

public void addEnv(org.apache.tools.ant.types.Environment.Variable 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()

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