Class TestSuite

java.lang.Object
com.sun.javatest.TestSuite

public class TestSuite extends Object
A class providing information about and access to the tests in a test suite. The primary methods to access and run the tests are
  • Field Details

    • DELETE_NONTEST_RESULTS

      public static final int DELETE_NONTEST_RESULTS
      Should tests which no longer exist in the test suite be deleted from a work directory when it is opened?
      See Also:
    • REFRESH_ON_RUN

      public static final int REFRESH_ON_RUN
      See Also:
    • CLEAR_CHANGED_TEST

      public static final int CLEAR_CHANGED_TEST
      Should a test be reset to not run if it is found that the test has changed in the test suite (test description does not match the one in the existing result).
      See Also:
    • TM_CONTEXT_NAME

      public static final String TM_CONTEXT_NAME
      See Also:
  • Constructor Details

    • TestSuite

      public TestSuite(File root, Map<String,String> tsInfo, ClassLoader cl)
      Create a TestSuite object.
      Parameters:
      root - The root file for this test suite.
      tsInfo - Test suite properties, typically read from the test suite properties file in the root directory of the test suite.
      cl - A class loader to be used to load additional classes as required, typically using a class path defined in the test suite properties file.
    • TestSuite

      public TestSuite(File root)
      Create a TestSuite object, with no additional test suite properties and no class loader.
      Parameters:
      root - The root file for this test suite.
  • Method Details

    • isTestSuite

      public static boolean isTestSuite(File root)
      Check if a file is the root of a valid test suite. A valid test suite is identified either by the root directory of the test suite, or by the file testsuite.html within that directory. The directory must contain either a test suite properties file (testsuite.jtt) or, for backwards compatibility, a file named testsuite.html.
      Parameters:
      root - The file to be checked.
      Returns:
      true if and only if root is the root of a valid test suite.
    • open

      Open a test suite.
      Parameters:
      root - A file identifying the root of the test suite.
      Returns:
      A TestSuite object for the test suite in question. The actual type of the result will depend on the test suite properties found in the root directory of the test suite.
      Throws:
      FileNotFoundException - if root does not exist.
      TestSuite.NotTestSuiteFault - if root does not identify a valid test suite.
      TestSuite.Fault - if any other problems occur while trying to open the test suite.
      See Also:
    • newInstance

      protected static <T> T newInstance(Class<? extends T> c) throws TestSuite.Fault
      Create a new instance of a class, translating any exceptions that may arise into Fault.
      Parameters:
      c - the class to be instantiated
      Returns:
      an instance of the specified class
      Throws:
      TestSuite.Fault - if any errors arise while trying to instantiate the class.
    • newInstance

      protected static <T> T newInstance(Class<? extends T> c, Class<?>[] argTypes, Object... args) throws TestSuite.Fault
      Create a new instance of a class using a non-default constructor, translating any exceptions that may arise into Fault.
      Parameters:
      c - the class to be instantiated
      argTypes - the types of the argument to be passed to the constructor, (thus implying the constructor to be used.)
      args - the arguments to be passed to the constructor
      Returns:
      an instance of the specified class
      Throws:
      TestSuite.Fault - if any errors arise while trying to instantiate the class.
    • loadClass

      protected static <T> Class<? extends T> loadClass(String className, ClassLoader cl) throws TestSuite.Fault
      Load a class using a specified loader, translating any errors that may arise into Fault.
      Parameters:
      className - the name of the class to be loaded
      cl - the class loader to use to load the specified class
      Returns:
      the class that was loaded
      Throws:
      TestSuite.Fault - if there was a problem loading the specified class
    • init

      protected void init(String... args) throws TestSuite.Fault
      Initialize this test suite, with args typically read from a .jtt file. The default implementation does not recognize any arguments and always throws an exception.
      Parameters:
      args - an array of strings to initialize this test suite object
      Throws:
      TestSuite.Fault - if there are any problems initializing the test suite from the specified arguments.
    • getPath

      public String getPath()
      Get the path for the root file of this test suite.
      Returns:
      the path for the root file of this test suite.
    • getRoot

      public File getRoot()
      Get the root file of this test suite.
      Returns:
      the root file of this test suite.
    • getRootDir

      public File getRootDir()
      Get the root directory of this test suite. If the root file is itself a directory, the result will be that directory; otherwise, the result will be the parent directory of the root file.
      Returns:
      the root directory of this test suite.
    • getTestsDir

      public File getTestsDir()
      Get the directory in the test suite that contains the tests. By default, the following are checked:
      1. The tests property in the test suite properties file. If this entry is found, it must either identify an absolute filename, or a directory relative to the test suite root directory, using '/' to separate the components of the path.
      2. If the file root/tests/testsuite.html exists, the result is the directory root/tests. This is for compatibility with standard TCK layout.
      3. Otherwise, the result is the root directory of the test suite.
      Returns:
      the directory that contains the tests
    • starting

      public void starting(Harness harness) throws TestSuite.Fault
      A notification method that is called when a test suite run is starting. The method may be used to do any test suite specific initialization. If overriding this method, be sure to call the superclass' method. It is fairly typical to register as a harness observer inside this method. Note that if an exception occurs during this method, it will be caught by the harness and reported as a Harness.Observer.error(). It is recommended that any implementations of this method register as an observer immediately so that they can catch this error and do any cleanup to abort the test suite startup sequence (check if services were started and close them down, etc).
      Parameters:
      harness - The harness that will be used to run the tests.
      Throws:
      TestSuite.Fault - if an error occurred while doing test suite-specific initialization that should cause the test run to be aborted.
    • createTestFilter

      public TestFilter createTestFilter(TestEnvironment filterEnv)
      Create a test suite specific filter to be used to filter the tests to be selected for a test run. The method should return null if no test suite specific filtering is required. The default is to return null.
      Parameters:
      filterEnv - Configuration data that may be used by the filter.
      Returns:
      a test suite filter, or null if no test suite specific filter is required for this test suite.
    • getTestFinder

      public TestFinder getTestFinder()
      Get a shared test finder to read the tests in this test suite.
      Returns:
      a test finder to read the tests in this test suite
      See Also:
    • setTestFinder

      protected void setTestFinder(TestFinder tf)
      Set the shared test finder used to read the tests in this test suite. Only one test finder may be set; attempts to change the test finder will cause IllegalStateException to be thrown. This method is normally called by TestSuite.open to initialize the finder to the result of calling createTestFinder.
      Parameters:
      tf - the test finder to be used
      Throws:
      IllegalStateException - if the test finder has previously been set to a different value
      See Also:
    • createTestFinder

      protected TestFinder createTestFinder() throws TestSuite.Fault
      Create a test finder to be used to access the tests in this test suite. The default implementation looks for a finder entry in the test suite properties file, which should identify the class to be used and any arguments it may require. The class will be loaded via the class loader specified when the test suite was opened, if one was given; otherwise, the system class loader will be used.

      The default implementation attempts to use a file testsuite.jtd in the tests directory. If found, a BinaryTestFinder will be created using this file. If it is not found, then it searches for a property named finder in the test suite properties and will attempt to instantiate that. If no entry is found or it is blank, an HTMLTestFinder is used, using whatever a basic settings HTMLTestFinder initializes to.

      Returns:
      a test finder to be used to read the tests in the test suite
      Throws:
      TestSuite.Fault - if there is a problem creating the test finder
      See Also:
    • createBinaryTestFinder

      protected TestFinder createBinaryTestFinder(String finderClassName, String[] finderArgs, File testsDir, File jtdFile) throws TestSuite.Fault
      In the case where a JTD file is found, attempt to load a binary test finder. The default implementation attempts to use the finder property in the test suite properties if it is a BinaryTestFinder subclass.
      Parameters:
      finderClassName - Finder class name to attempt to use as a BTF. Null if the default BTF class should be used.
      finderArgs - Arguments to finder given from the test suite property.
      testsDir - Reference location to pass to finder.
      jtdFile - Location of the JTD file to give to the BTF.
      Returns:
      The binary test finder which was created.
      Throws:
      TestSuite.Fault
      See Also:
    • createTestRunner

      public TestRunner createTestRunner()
      Create and initialize a TestRunner that can be used to run a series of tests. The default implementation returns a TestRunner that creates a number of test execution threads which each create and run a script for each test obtained from the test runners iterator.
      Returns:
      a TestRunner that can be used to run a series of tests
    • createScript

      public Script createScript(TestDescription td, String[] exclTestCases, TestEnvironment scriptEnv, WorkDirectory workDir, BackupPolicy backupPolicy) throws TestSuite.Fault
      Create and initialize a Script that can be used to run a test. The default implementation looks for a script entry in the configuration data provided, and if not found, looks for a script entry in the test suite properties. The script entry should define the script class to use and any arguments it may require. The class will be loaded via the class loader specified when the test suite was opened, if one was given; otherwise, the system class loader will be used. Individual test suites will typically use a more direct means to create an appropriate script object. The parameters for this method are normally passed through to the script that is created.

      Note that the name of this method is "create", it is not recommended that the value returned ever be re-used or cached for subsequent requests to this method.

      Parameters:
      td - The test description for the test to be executed.
      exclTestCases - Any test cases within the test that should not be executed.
      scriptEnv - Configuration data to be given to the test as necessary.
      workDir - A work directory in which to store the results of the test.
      backupPolicy - A policy object used to control how to backup any files that might be overwritten.
      Returns:
      a script to be used to execute the given test
      Throws:
      TestSuite.Fault - if any errors occur while creating the script
    • createInterview

      public InterviewParameters createInterview() throws TestSuite.Fault
      Create a configuration interview that can be used to collection the configuration data for a test run.

      The default implementation returns a default interview suitable for use with test suites built with earlier versions of the JT Harness: it provides questions equivalent to the fields in the GUI Parameter Editor or command-line -params option. As such, much of the necessary configuration data is provided indirectly via environment (.jte) files which must be created and updated separately.

      Individual test suites should provide their own interview, with questions customized to the configuration data they require.

      Note that the name of this method is "create", the harness may instantiate multiple copies for temporary use, resetting data or transferring data. Do not override this method with an implementation which caches the return value.

      Returns:
      A configuration interview to collect the configuration data for a test run.
      Throws:
      TestSuite.Fault - if a problem occurs while creating the interview
    • loadInterviewFromTemplate

      public InterviewParameters loadInterviewFromTemplate(Map<String,String> templateInfo, InterviewParameters newInterview)
      Create a configuration interview based on specified map of template values
      Returns:
      A configuration interview to collect the configuration data for a test run.
    • loadInterviewFromTemplate

      public InterviewParameters loadInterviewFromTemplate(File template, InterviewParameters ip) throws IOException
      Create a configuration interview based on specified template file
      Returns:
      A configuration interview to collect the configuration data for a test run. null if specified file is not template
      Throws:
      IOException
    • getID

      public String getID()
      Get a string containing a unique ID identifying this test suite, or null if not available. The default is taken from the "id" entry in the .jtt file.
      Returns:
      a unique ID identifying the test suite, or null if not specified.
      See Also:
    • getName

      public String getName()
      Get a string identifying this test suite, or null if not available. The default is taken from the "name" entry in the .jtt file. This string is for presentation to the user, and may be localized if appropriate.
      Returns:
      a string identifying the test suite, or null if not specified.
      See Also:
    • getEstimatedTestCount

      public int getEstimatedTestCount()
      Get the estimated number of tests in the test suite. The default is to use the value of the "testCount" property from the testsuite.jtt file.
      Returns:
      The estimated number of tests, or -1 if this number is not available.
    • getInitialExcludeList

      public File getInitialExcludeList()
      Get the file name of the initial exclude list associated with the test suite. The default is to use the value of the "initial.jtx" property from the testsuite.jtt file. If the value is a relative filename, it will be made absolute by evaluating it relative to the test suite root directory.
      Returns:
      the name of the default exclude list, or null if none specified.
    • hasInitialExcludeList

      public boolean hasInitialExcludeList()
      Check if the test suite has an initial exclude list. The default is to use getInitialExcludeList, and if that returns a non-null result, check whether that file exists or not.
      Returns:
      true if the test suite has an initial exclude list, and false otherwise
    • getLatestExcludeList

      public URL getLatestExcludeList()
      Get the URL for the latest exclude list associated with the test suite. The default is to use the value of the "latest.jtx" property from the testsuite.jtt file., which (if present) must be a fully qualified URL identifying the latest exclude list for this test suite.
      Returns:
      the name of the latest exclude list, or null if none specified.
    • hasLatestExcludeList

      public boolean hasLatestExcludeList()
      Check if the test suite has a latest exclude list. The default is to use getLatestExcludeList, and to check whether that return a non-null result. The URL is not itself checked for validity.
      Returns:
      true if the test suite has a latest exclude list, and false otherwise
    • getAdditionalDocNames

      public String[] getAdditionalDocNames()
      Get the names of any helpsets containing related documents for this test suite. The names should identify JavaHelp helpset files, as used by javax.help.HelpSet.findHelpSet(ClassLoader, String). Thus the names should identify resources of helpsets on the classpath. This means you will typically need to put the directory or jar file containing the help set on the classpath as well. By default, the names will be looked up under the name "additionalDocs" in the testsuite.jtt file.
      Returns:
      an array of names identifying helpsets that contain related documents for this testsuite. The result may be null if there are no such documents.
    • getKeywords

      public String[] getKeywords()
      Get the set of valid keywords for this test suite. By default, the keywords will be looked up under the name "keywords" in the testsuite.jtt file.
      Returns:
      the set of valid keywords for this test suite, or null if not known.
    • getFilesForTest

      public URL[] getFilesForTest(TestDescription td)
      Get a list of associated files for a specified test description. Normally, this will include the file containing the test description, and any source files used by the test. By default, the source files are determined from the test description's "source" entry.
      Parameters:
      td - The test description for which the associated files are required
      Returns:
      a list of associated files for this test description
      See Also:
    • getDocsForFolder

      public URL[] getDocsForFolder(String path)
      This method should be overridden in subclasses
      Parameters:
      path - String, which determines path to currently selected test's folder. This is root relative path. This shouldn't be null, for the root folder use "".
      Returns:
      array of files with documentation for test's folder, determined by path. null means there no documentation for this folder
    • getDocsForTest

      public URL[] getDocsForTest(TestDescription td)
      This method should be overridden in subclasses
      Parameters:
      td - TestDescription for currently selected test case. This shouldn't be null.
      Returns:
      array of files with documentation for test case, determined td. null means there no documentation for this test case
    • getLogo

      public URL getLogo()
      Get A URL identifying a logo for this test suite, or null if none available.
      Returns:
      a URL for a logo for the testsuite, or null if not available
    • loadClass

      public <T> Class<? extends T> loadClass(String className) throws TestSuite.Fault
      Load a class using the class loader provided when this test suite was created.
      Parameters:
      className - the name of the class to be loaded
      Returns:
      the class that was loaded
      Throws:
      TestSuite.Fault - if there was a problem loading the specified class
    • getClassLoader

      public ClassLoader getClassLoader()
      Get the class loader specified when this test suite object was created.
      Returns:
      the class loader specified when this test suite object was created
    • getServiceManager

      public com.sun.javatest.services.ServiceManager getServiceManager()
    • needServices

      public boolean needServices()
      Checks if serviceReader is active and file with service description does exist.
      Returns:
      true, if it's needed to start services, false otherwise.
    • getServiceReader

      public com.sun.javatest.services.ServiceReader getServiceReader()
      Returns a test suite specific ServiceReader, used to read Service definitions.
      Returns:
      ServiceReader instance. Default is PropertyServiceReader
    • getTestSuiteInfo

      protected Map<String,String> getTestSuiteInfo()
      Get a map containing the test suite data in the .jtt file.
      Returns:
      a map containing the test suite data in the .jtt file
    • getTestSuiteInfo

      public String getTestSuiteInfo(String name)
      Get an entry from the data in the .jtt file.
      Parameters:
      name - The name of the entry to get from the info in the .jtt file
      Returns:
      the value of the specified entry, or null if not found.
    • getTestRefreshBehavior

      public boolean getTestRefreshBehavior(int event)
      Get the requested behavior for dealing with conflicts between which tests are in the test suite vs those in the work directory.
      See Also:
    • getNotificationLog

      public Logger getNotificationLog(WorkDirectory wd)
      Returns notification logger associated with given working directory or common logger if null was specified
      Parameters:
      wd - - working directory or null
    • getObservedFile

      public com.sun.javatest.logging.ObservedFile getObservedFile(WorkDirectory wd)
    • getObservedFile

      public com.sun.javatest.logging.ObservedFile getObservedFile(String path)
    • createLog

      public Logger createLog(WorkDirectory wd, String b, String key) throws TestSuite.DuplicateLogNameFault
      Creates general purpose logger with given key and ResourceBundleName registered for given WorkDirectory.
      Parameters:
      wd - WorkDirectory logger should be registered for; may be null if no WorkDirectory currently available (the log will be registered for the first WD created for this TestSuite
      b - name of ResorceBundle used for this logger; may be null if not required
      key - key for this log
      Returns:
      general purpose logger with given key registered for given WorkDirectory or TestSuite (if WD is null)
      Throws:
      TestSuite.DuplicateLogNameFault - if log with this key has been registered in the system already
      See Also:
    • getLog

      public Logger getLog(WorkDirectory wd, String key) throws TestSuite.NoSuchLogFault
      Returns general purpose logger with given key registered for given WorkDirectory. The log should be created first.
      Parameters:
      wd - WorkDirectory desired logger is registered for
      key - key for this log
      Returns:
      general purpose logger with given key registered for given WorkDirectory
      Throws:
      TestSuite.NoSuchLogFault - if desired log not registered in the system
      NullPointerException - if wd is null
      See Also:
    • eraseLog

      public void eraseLog(WorkDirectory wd) throws IOException
      Cleans the log file in given WorkDirectory
      Parameters:
      wd - WorkDirectory desired logger is registered for
      Throws:
      IOException - if log file's content can't be erased
    • getHarness

      public Harness getHarness()