Class Harness


  • public class Harness
    extends java.lang.Object
    The object responsible for coordinating the execution of a test run.
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Harness.Fault
      This exception is used to report problems while executing a test run.
      static interface  Harness.Observer
      This interface provides a means for Harness to report on events that might be of interest as it executes.
    • Constructor Summary

      Constructors 
      Constructor Description
      Harness()
      Instantiate a harness.
      Harness​(java.io.File classDir)
      Deprecated.
      Use Harness() instead
    • Constructor Detail

      • Harness

        public Harness​(java.io.File classDir)
        Deprecated.
        Use Harness() instead
        Instantiate a harness.
        Parameters:
        classDir - The class dir to put in the environment for otherJVM tests
        See Also:
        Harness(), setClassDir(java.io.File)
      • Harness

        public Harness()
        Instantiate a harness.
    • Method Detail

      • setBackupPolicy

        public void setBackupPolicy​(BackupPolicy bp)
        Set the backup policy object to be used by this harness, used to determine the policy for backing up files before overwriting them.
        Parameters:
        bp - the backup policy object used by this harness
        See Also:
        getBackupPolicy()
      • isTracingRequired

        public boolean isTracingRequired()
        Check if a trace file should be generated while performing a test run.
        Returns:
        true if and only if a trace file should be generated
        See Also:
        setTracingRequired(boolean)
      • setTracingRequired

        public void setTracingRequired​(boolean b)
        Set whether a trace file should be generated while performing a test run.
        Parameters:
        b - whether or not a trace file should be generated
        See Also:
        isTracingRequired()
      • getClassDir

        public static java.io.File getClassDir()
        Get the class directory or jar file containing JT Harness.
        Returns:
        the class directory or jar file containing JT Harness
        See Also:
        setClassDir(java.io.File)
      • setClassDir

        public static void setClassDir​(java.io.File classDir)
        Specify the class directory or jar file containing JT Harness.
        Parameters:
        classDir - the class directory or jar file containing JT Harness
        See Also:
        getClassDir()
      • getParameters

        public Parameters getParameters()
        Get the current parameters of the harness.
        Returns:
        null if the parameters have not been set.
      • getEnv

        public TestEnvironment getEnv()
        Get the current test environment being used by the harness. This is similar to getParameters().getEnv(), except that the environment returned here has some standard additional fields set by the harness itself.
        Returns:
        null if the environment has not been set.
      • getResultTable

        public TestResultTable getResultTable()
        Get the current set of results. This will either be the set of results from which are currently running, or the results from the last run.
        Returns:
        null if no results are currently available. This will be the case if the Harness has not been run, or the parameters have been changed without doing a new run.
      • addObserver

        public void addObserver​(Harness.Observer o)
        Add an observer to be notified during the execution of a test run. Observers are notified of events in the reverse order they were added -- the most recently added observer gets notified first.
        Parameters:
        o - the observer to be added
        See Also:
        removeObserver(com.sun.javatest.Harness.Observer)
      • removeObserver

        public void removeObserver​(Harness.Observer o)
        Remove a previously registered observer so that it will no longer be notified during the execution of a test run. It is safe for observers to remove themselves during a notification; most obviously, an observer may remove itself during finishedTesting() or finishedTestRun().
        Parameters:
        o - the observer to be removed
        See Also:
        addObserver(com.sun.javatest.Harness.Observer)
      • start

        public void start​(Parameters p)
                   throws Harness.Fault
        Start running all the tests defined by a new set of parameters. The tests are run asynchronously, in a separate worker thread.
        Parameters:
        p - The parameters to be set when the tests are run. Any errors in the parameters are reported to any registered observers.
        Throws:
        Harness.Fault - if the harness is currently running tests and so cannot start running any more tests right now.
        See Also:
        isRunning(), stop(), waitUntilDone()
      • waitUntilDone

        public void waitUntilDone()
                           throws java.lang.InterruptedException
        Wait until the harness completes the current task.
        Throws:
        java.lang.InterruptedException - if the thread making the call is interrupted.
      • stop

        public void stop()
        Stop the harness executing any tests. If no tests are running, the method does nothing; otherwise it notifies any observers, and interrupts the thread doing the work. The worker may carry on for a short time after this method is called, while it waits for all the related tasks to complete.
        See Also:
        waitUntilDone()
      • batch

        public boolean batch​(Parameters params)
                      throws Harness.Fault,
                             java.lang.InterruptedException
        Run the tests defined by a new set of parameters.
        Parameters:
        params - The parameters to be used; they will be validated first.
        Returns:
        true if and only if all the selected tests were executed successfully, and all passed
        Throws:
        Harness.Fault - if the harness is currently running tests and cannot start running any more tests right now.
        java.lang.InterruptedException - if the thread making the call is interrupted, perhaps because of an asynchronous call of stop().
        See Also:
        isRunning(), stop(), waitUntilDone()
      • isBatchRun

        public boolean isBatchRun()
                           throws java.lang.IllegalStateException
        Was the harness invoked in batch mode? If it is not in batch mode, this typically implies that the user is using an interactive GUI interface.
        Returns:
        True if the harness is running and was invoked in batch mode.
        Throws:
        java.lang.IllegalStateException - If the harness is not running, care should be taken to handle this in case the run terminates.
      • isAllTestsFound

        public boolean isAllTestsFound()
        Indicates whether the harness has located all the tests it will execute. If true, then getTestsFoundCount() will return the number of test which will be executed during this test run; assuming the harness does not halt for special cases (errors, user request, etc...). If false, getTestsFoundCount() returns the number of tests located so far.
        Returns:
        True if all tests have been located. False if the harness is still looking for tests. Always false if the harness is not running.
        See Also:
        isRunning(), getTestsFoundCount()
      • getElapsedTime

        public long getElapsedTime()
        Find time since the start of the current or last run. If no run is in progress, this is the time it took to complete the last run.
        Returns:
        Zero if no run has ever been started yet. Elapsed time in milliseconds otherwise.
      • getStartTime

        public long getStartTime()
        Get the time at which the last run start.
        Returns:
        Time when the last run started in milliseconds. -1 if there is no previous run.
        See Also:
        getFinishTime()
      • getFinishTime

        public long getFinishTime()
        Get the time at which the last run finished. This is the time when the last test completed, and does not include post-run cleanup time.
        Returns:
        Time when the last run finished in milliseconds. -1 if there is no previous run or a run is in progress.
        See Also:
        getStartTime()
      • getCleanupFinishTime

        public long getCleanupFinishTime()
        Get the time at which cleanup of the entire run was completed. This is after the time when the last test completed.
        Returns:
        Time when the run finished in milliseconds. -1 if there is no previous run or a run is in progress.
        See Also:
        getStartTime()
      • getTotalCleanupTime

        public long getTotalCleanupTime()
      • getTotalSetupTime

        public long getTotalSetupTime()
      • getEstimatedTime

        public long getEstimatedTime()
        Find out the estimated time required to complete the remaining tests.
        Returns:
        A time estimate in milliseconds. Zero if no run is in progress or no estimate is available.
      • getTestsFoundCount

        public int getTestsFoundCount()
        Find out how many tests to run have been located so far. Data will pertain to the previous run (if any) if isRunning() is false. The return will be zero if isRunning() is false and there is no previous run for this instance of the Harness.
        Returns:
        Number of tests which the harness will try to run. Greater than or equal to zero and less than or equal to the total number of tests in the testsuite.
        See Also:
        isRunning()
      • setAutostopThreshold

        public void setAutostopThreshold​(int n)
        Set the threshold for automatic halting of a test run. The current algorithm is to begin at zero, add one for every failure, five for every error and subtract two for each pass. This value must be set before the run begins, do not change it during a run.
        See Also:
        getAutostopThreshold(int)