Package de.gebit.integrity.runner.console

## Class ConsoleTestExecutor

- java.lang.Object
- - de.gebit.integrity.runner.console.ConsoleTestExecutor

-     public class ConsoleTestExecutor
      extends Object

  A basic program to run Integrity tests from the console. This class has a main method, but you can also instantiate it on your own from a different entry point, like your own main method or similar. If you instantiate it for yourself, you can supply a setup class (subclass of `IntegrityDSLSetup`) which can be used to influence the Guice initialization, for example in order to replace certain services provided via Guice injection with subclasses of your own.
  There are various designated hooking points in this class which are designed to be overridden in subclasses, with the ultimate purpose of making it easy to implement common customizations with very little code (duplication).
  Author:
    Rene Schneider - initial API and implementation

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `enableZombieThreadWarning` | Whether to check for zombie threads at the end of test execution.
    `static int` | `EXIT_CODE_PARAMETER_ERROR` | Exit code returned on a parameter error (necessary parameter missing, unknown parameter given etc.).
    `static int` | `EXIT_CODE_RUNTIME_ERROR` | Exit code returned on a runtime error during test execution.
    `static int` | `EXIT_CODE_SUCCESS` | Exit code returned if everything went well.
    `protected Class<? extends IntegrityDSLSetup>` | `setupClass` | The setup class to use.
    `protected WeakHashMap<Thread,​Boolean>` | `threadsRunningBeforeTestExecution` | Stores a list of (weakly referenced) threads which were already running before the test run is started.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ConsoleTestExecutor()` | Creates a new instance using the default setup class.
    `ConsoleTestExecutor​(Class<? extends IntegrityDSLSetup> aSetupClass)` | Creates a new instance.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected void` | `addParameterizedConstants​(Map<String,​String> someParameterizedConstants)` | This method can be overridden to add some parameterized constants, which are defined in a test suite, if it is not desired to define those constants via VM arguments.
    `void` | `checkForZombieThreads()` | Searches for any threads still running which were not running when `prepareZombieThreadCheck()` was executed and prints them on the console.
    `protected List<TestRunnerCallback>` | `createAdditionalCallbacks()` | This is a designated override point to allow for additional callbacks to be easily integrated into a test run.
    `protected TestRunnerCallback` | `createConsoleTestCallback()` | Creates the console printout test runner callback.
    `protected TestResourceProvider` | `createResourceProvider​(List<File> aPathList)` | Creates the `TestResourceProvider` instance.
    `protected TestRunnerCallback` | `createXmlWriterTestCallback​(TestResourceProvider aResourceProvider, String anXmlFileName, String anExecutionName, TransformHandling aTransformHandling, boolean aCaptureConsoleFlag)` | Instantiates the XML Test Writer Callback which is used to write the XML test results.
    `protected TransformHandling` | `evaluateTransformHandling​(SimpleCommandLineParser.StringOption anXsltOption)` | Evaluates the given option and chooses a transformation handling from it.
    `protected String` | `getRootSuiteNameFrom​(String[] someRemainingParameters)` | Extracts the root suite name from the remaining parameters.
    `protected List<File>` | `getScriptsList​(String[] someRemainingParameters)` | Returns all script references from the remaining unparsed parameters.
    `protected PrintStream` | `getStdErr()` | Return the standard error stream to use.
    `protected PrintStream` | `getStdOut()` | Return the standard output stream to use.
    `protected TestRunner` | `initializeTestRunner​(TestModel aModel, TestRunnerCallback aCallback, Map<String,​String> someParameterizedConstants, String aResultLocale, Integer aRemotingPort, String aRemotingBindHost, Long aRandomSeed, String[] someCommandLineArguments)` | Initializes a `TestRunner` instance using the provided `TestModel`.
    `static void` | `main​(String[] someArgs)` | Main method.
    `void` | `prepareZombieThreadCheck()` | Takes note of all threads which are currently running by using the `threadsRunningBeforeTestExecution` map.
    `protected List<Thread>` | `retrieveListOfAllThreads()` | Gets a list of all threads known to the JVM.
    `int` | `run​(String[] someArgs)` | This is basically the actual "main" method.
    `protected void` | `runTests​(TestRunner aRunner, SuiteDefinition aRootSuite, VariantDefinition aVariant, boolean aBlockForRemotingFlag)` | Run the tests on the provided `TestRunner`.
    `int` | `runWithZombieThreadDetection​(String[] someArgs)` | Works like `run(String[])`, but performs zombie thread detection as well.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### EXIT_CODE_SUCCESS

          public static final int EXIT_CODE_SUCCESS

      Exit code returned if everything went well.
      See Also:
        Constant Field Values

    - #### EXIT_CODE_PARAMETER_ERROR

          public static final int EXIT_CODE_PARAMETER_ERROR

      Exit code returned on a parameter error (necessary parameter missing, unknown parameter given etc.).
      See Also:
        Constant Field Values

    - #### EXIT_CODE_RUNTIME_ERROR

          public static final int EXIT_CODE_RUNTIME_ERROR

      Exit code returned on a runtime error during test execution.
      See Also:
        Constant Field Values

    - #### setupClass

          protected Class<? extends IntegrityDSLSetup> setupClass

      The setup class to use.

    - #### threadsRunningBeforeTestExecution

          protected WeakHashMap<Thread,​Boolean> threadsRunningBeforeTestExecution

      Stores a list of (weakly referenced) threads which were already running before the test run is started.

    - #### enableZombieThreadWarning

          protected boolean enableZombieThreadWarning

      Whether to check for zombie threads at the end of test execution.

  - ### Constructor Detail

    - #### ConsoleTestExecutor

          public ConsoleTestExecutor()

      Creates a new instance using the default setup class.

    - #### ConsoleTestExecutor

          public ConsoleTestExecutor​(Class<? extends IntegrityDSLSetup> aSetupClass)

      Creates a new instance.
      Parameters:
        `aSetupClass` - the setup class to use

  - ### Method Detail

    - #### main

          public static void main​(String[] someArgs)

      Main method.
      Parameters:
        `someArgs` -

    - #### prepareZombieThreadCheck

          public void prepareZombieThreadCheck()

      Takes note of all threads which are currently running by using the `threadsRunningBeforeTestExecution` map. This is used in conjunction with `checkForZombieThreads()`.

    - #### retrieveListOfAllThreads

          protected List<Thread> retrieveListOfAllThreads()

      Gets a list of all threads known to the JVM. Due to the Thread API it is non-trivial to get such a list reliably, which is why that is encapsulated here. The returned list is guaranteed to not contain null items.
      Returns:
        a list of threads

    - #### checkForZombieThreads

          public void checkForZombieThreads()

      Searches for any threads still running which were not running when `prepareZombieThreadCheck()` was executed and prints them on the console. This mechanism is designed to find

    - #### runWithZombieThreadDetection

          public int runWithZombieThreadDetection​(String[] someArgs)

      Works like `run(String[])`, but performs zombie thread detection as well. See `checkForZombieThreads()` for details.
      Parameters:
        `someArgs` - the command-line arguments
      Returns:
        the exit code

    - #### run

          public int run​(String[] someArgs)

      This is basically the actual "main" method. It instantiates the test model, runner etc. and executes the test.
      Parameters:
        `someArgs` - the command-line arguments
      Returns:
        the exit code

    - #### getStdErr

          protected PrintStream getStdErr()

      Return the standard error stream to use.
      Returns:
        the standard error stream

    - #### getStdOut

          protected PrintStream getStdOut()

      Return the standard output stream to use.
      Returns:
        the standard output stream

    - #### createConsoleTestCallback

          protected TestRunnerCallback createConsoleTestCallback()

      Creates the console printout test runner callback. This is an override spot for subclasses.
      Returns:
        the console test callback to use

    - #### createXmlWriterTestCallback

          protected TestRunnerCallback createXmlWriterTestCallback​(TestResourceProvider aResourceProvider,
                                                                   String anXmlFileName,
                                                                   String anExecutionName,
                                                                   TransformHandling aTransformHandling,
                                                                   boolean aCaptureConsoleFlag)

      Instantiates the XML Test Writer Callback which is used to write the XML test results. This is an override spot for subclasses.
      Parameters:
        `aResourceProvider` - the resource provider to use (classloader is taken from there)
        `anXmlFileName` - the file to write the result into
        `anExecutionName` - the title of the result
        `aTransformHandling` - how the XML -> XHTML transform shall be handled
        `aCaptureConsoleFlag` - whether stdout and stderr shall be captured
      Returns:
        the XML test writer callback to use

    - #### getRootSuiteNameFrom

          protected String getRootSuiteNameFrom​(String[] someRemainingParameters)

      Extracts the root suite name from the remaining parameters.
      Parameters:
        `someRemainingParameters` - Where to extract the root suite name from.
      Returns:
        the root suite name

    - #### getScriptsList

          protected List<File> getScriptsList​(String[] someRemainingParameters)

      Returns all script references from the remaining unparsed parameters.
      Parameters:
        `someRemainingParameters` - Unparsed parameters not matched by the options.
      Returns:
        List of script file references.

    - #### evaluateTransformHandling

          protected TransformHandling evaluateTransformHandling​(SimpleCommandLineParser.StringOption anXsltOption)

      Evaluates the given option and chooses a transformation handling from it.
      Parameters:
        `anXsltOption` - Option to be evaluated.
      Returns:
        The chosen transformation handling.

    - #### createAdditionalCallbacks

          protected List<TestRunnerCallback> createAdditionalCallbacks()

      This is a designated override point to allow for additional callbacks to be easily integrated into a test run. Any callbacks returned here are added to the basic callbacks created for a test run (usually a console output callback and an XML file output callback, but these can be customized by startup options).
      Returns:

    - #### addParameterizedConstants

          protected void addParameterizedConstants​(Map<String,​String> someParameterizedConstants)

      This method can be overridden to add some parameterized constants, which are defined in a test suite, if it is not desired to define those constants via VM arguments. The default implementation does nothing.
      Parameters:
        `someParameterizedConstants` - the map containing the constants and their values

    - #### createResourceProvider

          protected TestResourceProvider createResourceProvider​(List<File> aPathList)
                                                         throws IOException

      Creates the `TestResourceProvider` instance.
      Parameters:
        `aPathList` - the list with the test script paths
      Returns:
        a resource provider instance
      Throws:
        `IOException`

    - #### initializeTestRunner

          protected TestRunner initializeTestRunner​(TestModel aModel,
                                                    TestRunnerCallback aCallback,
                                                    Map<String,​String> someParameterizedConstants,
                                                    String aResultLocale,
                                                    Integer aRemotingPort,
                                                    String aRemotingBindHost,
                                                    Long aRandomSeed,
                                                    String[] someCommandLineArguments)
                                             throws IOException

      Initializes a `TestRunner` instance using the provided `TestModel`.
      Parameters:
        `aModel` - the model
        `aCallback` - the callback to use
        `someParameterizedConstants` - all parameterized constants to provide to the test runner
        `aResultLocale` - the locale to be used for the test result generation (if not provided, use the non-localized default strings, which usually are in English)
        `aRemotingPort` - the remoting port to use by the test runner
        `aRemotingBindHost` - the host to bind the remoting port to
        `aRandomSeed` - the seed value for the RNG
        `someCommandLineArguments` - the command line arguments to use for forking
      Returns:
        the initialized test runner
      Throws:
        `IOException`

    - #### runTests

          protected void runTests​(TestRunner aRunner,
                                  SuiteDefinition aRootSuite,
                                  VariantDefinition aVariant,
                                  boolean aBlockForRemotingFlag)

      Run the tests on the provided `TestRunner`.
      Parameters:
        `aRunner` - the runner
        `aRootSuite` - the root suite to run
        `aVariant` - the variant to run
        `aBlockForRemotingFlag` - whether to wait for remoting to start the tests