Package com.carrotsearch.ant.tasks.junit4

Class JUnit4

  • All Implemented Interfaces:
    java.lang.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).

    • Constructor Detail

      • JUnit4

        public JUnit4()

    • Method Detail

      • setJvmOutputAction

        public void setJvmOutputAction​(java.lang.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).

      • 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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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.

      • 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​(java.lang.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​(java.io.File dir)
        The directory to invoke forked VMs in.

      • setTempDir

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

      • setIfNoTests

        public void setIfNoTests​(java.lang.String value)
        What to do when no tests were executed (all tests were ignored)?
        See Also:
        JUnit4.NoTestsAction

      • 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​(java.lang.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​(java.lang.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)).

      • 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​(java.lang.String forkMode)

      • setHaltOnError

        public void setHaltOnError​(boolean haltOnError)

      • setFiltertrace

        public void setFiltertrace​(boolean filterTrace)

      • setTimeout

        public void setTimeout​(java.lang.String v)

      • setIncludeantruntime

        public void setIncludeantruntime​(java.lang.String v)

      • setShowoutput

        public void setShowoutput​(java.lang.String v)

      • setOutputtoformatters

        public void setOutputtoformatters​(java.lang.String v)

      • setReloading

        public void setReloading​(java.lang.String v)

      • setClonevm

        public void setClonevm​(java.lang.String v)

      • setErrorproperty

        public void setErrorproperty​(java.lang.String v)

      • setLogfailedtests

        public void setLogfailedtests​(java.lang.String v)

      • setEnableTestListenerEvents

        public void setEnableTestListenerEvents​(java.lang.String v)

      • createFormatter

        public java.lang.Object createFormatter()

      • createTest

        public java.lang.Object createTest()

      • createBatchtest

        public java.lang.Object createBatchtest()

      • warnUnsupported

        private void warnUnsupported​(java.lang.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​(java.lang.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 java.util.List<java.lang.String> listFiles​(java.nio.file.Path f)
                                                   throws java.io.IOException
        Throws:
        java.io.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 java.util.List<java.lang.String> loadBalanceSuites​(java.util.List<ForkedJvmInfo> jvmInfo,
                                                           TestsCollection testsCollection,
                                                           java.util.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 java.util.Map<java.lang.Boolean,​java.util.List<java.lang.String>> sortAndSplitReplicated​(java.util.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 java.lang.Exception
        Attach listeners and execute a slave process.
        Throws:
        java.lang.Exception

      • checkJvmOutput

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

      • tempFile

        private java.nio.file.Path tempFile​(java.lang.String uniqueSeed,
                                    java.lang.String base,
                                    java.lang.String suffix,
                                    java.nio.file.Path tempDir)
                             throws java.io.IOException
        Throws:
        java.io.IOException

      • escapeAndJoin

        private java.lang.String escapeAndJoin​(java.lang.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,
                                                          java.io.InputStream eventStream,
                                                          java.io.OutputStream sysout,
                                                          java.io.OutputStream syserr,
                                                          java.io.RandomAccessFile streamsBuffer)
        Execute a slave process. Pump events to the given event bus.

      • getWorkingDirectory

        private java.nio.file.Path getWorkingDirectory​(ForkedJvmInfo jvmInfo)
                                        throws java.io.IOException
        Throws:
        java.io.IOException

      • getTempDir

        private java.nio.file.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).