Class JUnit4
- All Implemented Interfaces:
Cloneable
- 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
Nested ClassesModifier and TypeClassDescriptionstatic class
APropertySet
with an additional attribute specifying whether or not empty values should be propagated or ignored.static class
AEnvironment.Variable
with an additional attribute specifying whether or not empty values should be propagated or ignored.static enum
What to do on JVM output?static enum
What to do when there were no executed tests (all ignored or none at all?). -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Name of the antlib resource inside JUnit4 JAR.private List
<SuiteBalancer> Balancers scheduling tests for individual JVMs in parallel mode.private org.apache.tools.ant.types.Path
private static final String
System property passed to forked VMs: current working directory (absolute).private org.apache.tools.ant.types.Path
Multiple path resolution inCommandlineJava.getCommandline()
is very slow so we construct and canonicalize paths.private boolean
static final boolean
Default value ofsetDebugStream(boolean)
.static final float
Default value ofsetDynamicAssignmentRatio(float)
static final boolean
Default value ofsetHaltOnFailure(boolean)
.static final boolean
Default value ofsetIsolateWorkingDirectories(boolean)
.static final NonEmptyWorkDirectoryAction
Default valkue ofsetOnNonEmptyWorkDirectory(java.lang.String)
.static final String
Default value ofsetParallelism(java.lang.String)
.static final boolean
Default value ofsetPrintSummary(boolean)
.static final boolean
Default value ofsetShuffleOnSlave(boolean)
.static final boolean
Default value ofsetSysouts(boolean)
.static final boolean
Default value ofsetUniqueSuiteNames(boolean)
private Path
Directory to invoke forked VMs in.private float
private org.apache.tools.ant.types.Environment
Environment variables to use in the forked JVM.private String
Property to set if there were test failures or errors.private boolean
Stop the build process if there were errors?private long
private JUnit4.NoTestsAction
private boolean
private boolean
Set to true to leave temporary files (for diagnostics).Listeners listening on the event bus.private boolean
Set new environment for the forked process?private NonEmptyWorkDirectoryAction
private String
static final Object
static final String
private boolean
Print summary of all tests at the end.private String
private final org.apache.tools.ant.types.resources.Resources
Test names.private boolean
private org.apache.tools.ant.types.CommandlineJava
Slave VM command line.private String
private boolean
private Path
A folder to store temporary files in.A list of temporary files to leave or remove if build passes.private org.apache.tools.ant.AntClassLoader
Class loader used to resolve annotations and classes referenced from annotations whenDescription
s containing them are passed from slaves.private boolean
private static String[]
Welcome messages.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 -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
Adds a system property to any forked JVM.void
Adds a set of properties that will be used as system properties that tests can access.void
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.private org.apache.tools.ant.types.Path
Adds a classpath source which contains the given resource.private void
checkJvmOutput
(com.google.common.eventbus.EventBus aggregatedBus, Path file, ForkedJvmInfo forked, String fileName) Creates a new list of balancers.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
Add an additional argument to any forked JVM.Creates a new list of listeners.private int
determineForkedJvmCount
(TestsCollection testCollection) Determine how many forked JVMs to use.private String
escapeAndJoin
(String[] commandline) Try to provide an escaped, ready-to-use shell line to repeat a given command line.void
execute()
private void
executeSlave
(ForkedJvmInfo slave, com.google.common.eventbus.EventBus aggregatedBus) Attach listeners and execute a slave process.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.private org.apache.tools.ant.types.CommandlineJava
Returns the slave VM command line.getSeed()
private Path
Resolve temporary folder.private Path
getWorkingDirectory
(ForkedJvmInfo jvmInfo) boolean
loadBalanceSuites
(List<ForkedJvmInfo> jvmInfo, TestsCollection testsCollection, List<SuiteBalancer> balancers) Perform load balancing of the set of suites.private long
Return the master seed ofgetSeed()
.private TestsCollection
Process test resources.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.void
setClonevm
(String v) void
setDebugStream
(boolean debugStream) Enables a debug stream from each forked JVM.void
The directory to invoke forked VMs in.void
setDynamicAssignmentRatio
(float ratio) Specifies the ratio of suites moved to dynamic assignment list.void
void
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
setIfNoTests
(String value) What to do when no tests were executed (all tests were ignored)?void
void
setIsolateWorkingDirectories
(boolean isolateWorkingDirectories) If set totrue
each slave JVM gets a separate working directory under whatever is set insetDir(File)
.void
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
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
setOnNonEmptyWorkDirectory
(String value) Determines the behavior on detecting non-empty existing current working directory for a forked JVM, before the tests commence.void
void
setParallelism
(String parallelism) The number of parallel slaves.void
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
void
Initial random seed used for shuffling test suites and other sources of pseudo-randomness.void
void
setShuffleOnSlave
(boolean shuffle) Predictably shuffle tests order after balancing.void
setStatsPropertyPrefix
(String statsPropertyPrefix) Sets the property prefix to which test statistics are saved.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.sortAndSplitReplicated
(List<TestClass> testClasses) private Path
private void
Validate arguments.private void
Validate JUnit4 presence in a concrete version.private void
warnUnsupported
(String attName) 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
-
Field Details
-
WELCOME_MESSAGES
Welcome messages. -
ANTLIB_RESOURCE_NAME
Name of the antlib resource inside JUnit4 JAR.- See Also:
-
PARALLELISM_AUTO
- See Also:
-
PARALLELISM_MAX
- See Also:
-
DEFAULT_SHUFFLE_ON_SLAVE
public static final boolean DEFAULT_SHUFFLE_ON_SLAVEDefault value ofsetShuffleOnSlave(boolean)
.- See Also:
-
DEFAULT_PARALLELISM
Default value ofsetParallelism(java.lang.String)
.- See Also:
-
DEFAULT_PRINT_SUMMARY
public static final boolean DEFAULT_PRINT_SUMMARYDefault value ofsetPrintSummary(boolean)
.- See Also:
-
DEFAULT_HALT_ON_FAILURE
public static final boolean DEFAULT_HALT_ON_FAILUREDefault value ofsetHaltOnFailure(boolean)
.- See Also:
-
DEFAULT_ISOLATE_WORKING_DIRECTORIES
public static final boolean DEFAULT_ISOLATE_WORKING_DIRECTORIESDefault value ofsetIsolateWorkingDirectories(boolean)
.- See Also:
-
DEFAULT_NON_EMPTY_WORKDIR_ACTION
Default valkue ofsetOnNonEmptyWorkDirectory(java.lang.String)
. -
DEFAULT_DYNAMIC_ASSIGNMENT_RATIO
public static final float DEFAULT_DYNAMIC_ASSIGNMENT_RATIODefault value ofsetDynamicAssignmentRatio(float)
- See Also:
-
DEFAULT_SYSOUTS
public static final boolean DEFAULT_SYSOUTSDefault value ofsetSysouts(boolean)
.- See Also:
-
DEFAULT_DEBUGSTREAM
public static final boolean DEFAULT_DEBUGSTREAMDefault value ofsetDebugStream(boolean)
.- See Also:
-
DEFAULT_UNIQUE_SUITE_NAME
public static final boolean DEFAULT_UNIQUE_SUITE_NAMEDefault value ofsetUniqueSuiteNames(boolean)
- See Also:
-
CHILDVM_SYSPROP_CWD
System property passed to forked VMs: current working directory (absolute).- See Also:
-
jvmOutputAction
- See Also:
-
sysouts
private boolean sysouts- See Also:
-
debugStream
private boolean debugStream- See Also:
-
slaveCommand
private org.apache.tools.ant.types.CommandlineJava slaveCommandSlave VM command line. -
newEnvironment
private boolean newEnvironmentSet new environment for the forked process? -
uniqueSuiteNames
private boolean uniqueSuiteNames- See Also:
-
env
private org.apache.tools.ant.types.Environment envEnvironment variables to use in the forked JVM. -
dir
Directory to invoke forked VMs in. -
resources
private final org.apache.tools.ant.types.resources.Resources resourcesTest names. -
haltOnFailure
private boolean haltOnFailureStop the build process if there were errors? -
printSummary
private boolean printSummaryPrint summary of all tests at the end. -
failureProperty
Property to set if there were test failures or errors. -
tempDir
A folder to store temporary files in. Defaults todir
or the project's basedir. -
listeners
Listeners listening on the event bus. -
balancers
Balancers scheduling tests for individual JVMs in parallel mode. -
testsClassLoader
private org.apache.tools.ant.AntClassLoader testsClassLoaderClass loader used to resolve annotations and classes referenced from annotations whenDescription
s containing them are passed from slaves. -
parallelism
- See Also:
-
leaveTemporary
private boolean leaveTemporarySet to true to leave temporary files (for diagnostics). -
temporaryFiles
A list of temporary files to leave or remove if build passes. -
random
- See Also:
-
isolateWorkingDirectories
private boolean isolateWorkingDirectories- See Also:
-
nonEmptyWorkDirAction
- See Also:
-
classpath
private org.apache.tools.ant.types.Path classpathMultiple path resolution inCommandlineJava.getCommandline()
is very slow so we construct and canonicalize paths. -
bootclasspath
private org.apache.tools.ant.types.Path bootclasspath -
dynamicAssignmentRatio
private float dynamicAssignmentRatio- See Also:
-
shuffleOnSlave
private boolean shuffleOnSlave- See Also:
-
heartbeat
private long heartbeat- See Also:
-
ifNoTests
- See Also:
-
statsPropertyPrefix
- See Also:
-
-
Constructor Details
-
JUnit4
public JUnit4()
-
-
Method Details
-
setJvmOutputAction
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 istrue
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
The number of parallel slaves. Can be set to a constant "max" for the number of cores returned fromRuntime.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
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
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
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
- 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 classorg.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
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
The directory to invoke forked VMs in. -
setTempDir
The directory to store temporary files in. -
setIfNoTests
What to do when no tests were executed (all tests were ignored)?- See Also:
-
addConfiguredSysproperty
Adds a system property to any forked JVM. -
addConfiguredSyspropertyset
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
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 totrue
each slave JVM gets a separate working directory under whatever is set insetDir(File)
. The directory naming for each slave follows: "Snum", where num is slave's number. Directories are created automatically and removed unlesssetLeaveTemporary(boolean)
is set totrue
. -
setOnNonEmptyWorkDirectory
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 (seesetIsolateWorkingDirectories(boolean)
). -
addEnv
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
Creates a new list of listeners. -
addAssertions
public void addAssertions(org.apache.tools.ant.types.Assertions asserts) Add assertions to tests execution. -
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
-
setHaltOnError
public void setHaltOnError(boolean haltOnError) -
setFiltertrace
public void setFiltertrace(boolean filterTrace) -
setTimeout
-
setIncludeantruntime
-
setShowoutput
-
setOutputtoformatters
-
setReloading
-
setClonevm
-
setErrorproperty
-
setLogfailedtests
-
setEnableTestListenerEvents
-
createFormatter
-
createTest
-
createBatchtest
-
warnUnsupported
-
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
Sets the property prefix to which test statistics are saved. -
execute
public void execute() throws org.apache.tools.ant.BuildException- Overrides:
execute
in classorg.apache.tools.ant.Task
- Throws:
org.apache.tools.ant.BuildException
-
listFiles
- Throws:
IOException
-
validateArguments
private void validateArguments() throws org.apache.tools.ant.BuildExceptionValidate arguments.- Throws:
org.apache.tools.ant.BuildException
-
validateJUnit4
private void validateJUnit4() throws org.apache.tools.ant.BuildExceptionValidate 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. SetsForkedJvmInfo.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
-
masterSeed
private long masterSeed()Return the master seed ofgetSeed()
. -
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
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
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
- Throws:
IOException
-
getTempDir
Resolve temporary folder. -
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).
-