JUnit4 (RandomizedTesting JUnit4 ANT Task v2.0.3 API Documentation (JavaDoc))

Overview

Package

Class

Tree

Deprecated

Index

Help

RandomizedTesting JUnit4 ANT Task v2.0.3
API Documentation

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

Nested Class Summary
`static class`	`JUnit4.ExtendedPropertySet` A `PropertySet` with an additional attribute specifying whether or not empty values should be propagated or ignored.
`static class`	`JUnit4.ExtendedVariable` A `Environment.Variable` with an additional attribute specifying whether or not empty values should be propagated or ignored.
`static class`	`JUnit4.JvmOutputAction` What to do on JVM output?

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 boolean`	`DEFAULT_SYSOUTS` Default value of `setSysouts(boolean)`.
`EnumSet<JUnit4.JvmOutputAction>`	`jvmOutputAction`
`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(JUnit4.ExtendedVariable sysp)` Adds a system property to any forked JVM.
`void`	`addConfiguredSyspropertyset(JUnit4.ExtendedPropertySet sysp)` Adds a set of properties that will be used as system properties that tests can access.
`void`	`addEnv(JUnit4.ExtendedVariable 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.
`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`	`setHeartbeat(long heartbeat)` Sets the heartbeat used to detect inactive/ hung forked tests (JVMs) to the given number of seconds.
`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`	`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.
`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`	`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".
`void`	`setTempDir(File tempDir)` The directory to store temporary files in.
`void`	`setTimeout(String v)`
`void`	`setUniqueSuiteNames(boolean uniqueSuiteNames)` Allow or disallow duplicate suite names in resource collections.

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

DEFAULT_SYSOUTS

public static final boolean DEFAULT_SYSOUTS

Default value of setSysouts(boolean).

See Also:: Constant Field Values

jvmOutputAction

public EnumSet<JUnit4.JvmOutputAction> jvmOutputAction

See Also:: setJvmOutputAction(String)

Constructor Detail

JUnit4

public JUnit4()

Method Detail

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

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

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

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)