Package de.gebit.integrity.runner.callbacks

## Class TestRunnerCallback

- java.lang.Object
- - de.gebit.integrity.runner.callbacks.TestRunnerCallback

- Direct Known Subclasses:
    `AbstractTestRunnerCallback`, `CompoundTestRunnerCallback`

      public abstract class TestRunnerCallback
      extends Object

  During test execution, the test runner invokes a callback in order to report progress as well as test results. A callback can then use this information for whatever purpose; usually writing test output files.
  Author:
    Rene Schneider - initial API and implementation

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected boolean` | `dryRun` | Whether the current phase is a dry run.
    `protected ForkDefinition` | `forkInExecution` | The fork that is currently being executed.
    `protected IntegrityRemotingServer` | `server` | The remoting server, required for callback-to-callback communication in master-fork situations.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TestRunnerCallback()` |

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ForkDefinition` | `getForkInExecution()` |
    `boolean` | `isDryRun()` |
    `boolean` | `isFork()` |
    `abstract void` | `onAbortExecution​(String anAbortExecutionMessage, String anAbortExecutionStackTrace)` | Called when test execution is aborted prematurely due to an `AbortExecutionException` - either thrown locally or by a fork.
    `void` | `onCallbackProcessingEnd()` | Called after a call has been performed on all callbacks.
    `void` | `onCallbackProcessingStart()` | Called when a call to all callbacks is imminent.
    `abstract void` | `onCallFinish​(Call aCall, CallResult aResult)` | Called right after a call was executed.
    `abstract void` | `onCallStart​(Call aCall)` | Called before a call is being executed.
    `abstract void` | `onConstantDefinition​(ConstantEntity aDefinition, SuiteDefinition aSuite, Object aValue, boolean aParameterizedFlag)` | Called when a constant is being defined.
    `abstract void` | `onExecutionFinish​(TestModel aModel, SuiteSummaryResult aResult)` | Called after all execution has been finished.
    `abstract void` | `onExecutionStart​(TestModel aModel, VariantDefinition aVariant)` | Called when the execution starts, that is, before the first (root) suite is entered.
    `abstract void` | `onMessageFromFork​(TestRunnerCallbackMethods aMethod, Serializable... someObjects)` | Called when a fork has sent a message to the masters' callback.
    `abstract void` | `onReturnVariableAssignment​(SuiteReturn aReturn, VariableEntity aSource, VariableEntity aTarget, Suite aSuite, Object aValue)` | Called when a return variable value from a suite is assigned to the respective local variable in the calling suite.
    `abstract void` | `onSetupFinish​(SuiteDefinition aSetupSuite, SuiteResult aResult)` | Called when a setup suite has been executed.
    `abstract void` | `onSetupSkipped​(SuiteDefinition aSetupSuite, SuiteSkipReason aReason)` | Called when a setup suite is being skipped.
    `abstract void` | `onSetupStart​(SuiteDefinition aSetupSuite)` | Called when a setup suite is being called.
    `abstract void` | `onSuiteFinish​(Suite aSuite, SuiteSummaryResult aResult)` | Called after a suite has finished execution.
    `abstract void` | `onSuiteSkipped​(Suite aSuite, SuiteSkipReason aReason)` | Called when a suite call is being skipped.
    `abstract void` | `onSuiteStart​(Suite aSuite)` | Called when a suite call is being followed.
    `abstract void` | `onTableTestFinish​(TableTest aTableTest, TestResult aResult)` | Called after a tabletest was fully executed (all rows have been executed).
    `abstract void` | `onTableTestRowFinish​(TableTest aTableTest, TableTestRow aRow, TestSubResult aSubResult)` | Called after a table test row has been executed.
    `abstract void` | `onTableTestRowStart​(TableTest aTableTest, TableTestRow aRow)` | Called when a single row of a table test is about to be executed.
    `abstract void` | `onTableTestStart​(TableTest aTableTest)` | Called when a table test is about to be executed.
    `abstract void` | `onTearDownFinish​(SuiteDefinition aTearDownSuite, SuiteResult aResult)` | Called after a teardown suite was executed.
    `abstract void` | `onTearDownSkipped​(SuiteDefinition aTearDownSuite, SuiteSkipReason aReason)` | Called when a teardown suite is being skipped.
    `abstract void` | `onTearDownStart​(SuiteDefinition aTearDownSuite)` | Called before a teardown suite is being executed.
    `abstract void` | `onTestFinish​(Test aTest, TestResult aResult)` | Called after a test was executed.
    `abstract void` | `onTestStart​(Test aTest)` | Called right before a test is being executed.
    `abstract void` | `onTimeSetFinish​(TimeSet aTimeSet, TimeSetResult aResult)` | Called when the test time was set.
    `abstract void` | `onTimeSetStart​(TimeSet aTimeSet, SuiteDefinition aSuite, List<ForkDefinition> someForks)` | Called when the test time will be set.
    `abstract void` | `onVariableAssignment​(VariableAssignment anAssignment, VariableEntity aDefinition, SuiteDefinition aSuite, Object aValue)` | Called when a variable is being assigned.
    `abstract void` | `onVariableDefinition​(VariableEntity aDefinition, SuiteDefinition aSuite, Object anInitialValue)` | Called when a variable is being defined.
    `abstract void` | `onVisibleComment​(String aCommentText, boolean anIsTitle, VisibleComment aCommentElement)` | Called when a visible comment is encountered during execution.
    `abstract void` | `onVisibleDivider​(String aDividerText, VisibleDivider aDividerElement)` | Called when a visible divider is encountered during execution.
    `void` | `receiveFromFork​(String aCallbackClassName, TestRunnerCallbackMethods aMethod, Serializable[] someData)` | This method is used by the test runner to forward messages received from the forks to the callback.
    `protected void` | `sendToMaster​(TestRunnerCallbackMethods aMethod, Serializable... someObjects)` | When a callback that is running inside a fork instance uses this method, the given objects and the method parameter are being sent to the respective callback instance on the master.
    `void` | `setDryRun​(boolean aDryRun)` |
    `void` | `setForkInExecution​(ForkDefinition aFork)` |
    `void` | `setRemotingServer​(IntegrityRemotingServer aRemotingServer)` |

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

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

- - ### Field Detail

    - #### server

          protected IntegrityRemotingServer server

      The remoting server, required for callback-to-callback communication in master-fork situations.

    - #### dryRun

          protected boolean dryRun

      Whether the current phase is a dry run.

    - #### forkInExecution

          protected ForkDefinition forkInExecution

      The fork that is currently being executed.

  - ### Constructor Detail

    - #### TestRunnerCallback

          public TestRunnerCallback()

  - ### Method Detail

    - #### onCallbackProcessingStart

          public void onCallbackProcessingStart()

      Called when a call to all callbacks is imminent.

    - #### onCallbackProcessingEnd

          public void onCallbackProcessingEnd()

      Called after a call has been performed on all callbacks.

    - #### onExecutionStart

          public abstract void onExecutionStart​(TestModel aModel,
                                                VariantDefinition aVariant)

      Called when the execution starts, that is, before the first (root) suite is entered. This is always the first call of an execution phase.
      Parameters:
        `aModel` - the test model that will be executed

    - #### onSuiteStart

          public abstract void onSuiteStart​(Suite aSuite)

      Called when a suite call is being followed.
      Parameters:
        `aSuite` - the suite call that will be entered

    - #### onSuiteSkipped

          public abstract void onSuiteSkipped​(Suite aSuite,
                                              SuiteSkipReason aReason)

      Called when a suite call is being skipped.
      Parameters:
        `aSuite` - the suite being skipped
        `aReason` - the reason for the skipping

    - #### onSetupStart

          public abstract void onSetupStart​(SuiteDefinition aSetupSuite)

      Called when a setup suite is being called.
      Parameters:
        `aSetupSuite` - the setup suite being entered

    - #### onSetupSkipped

          public abstract void onSetupSkipped​(SuiteDefinition aSetupSuite,
                                              SuiteSkipReason aReason)

      Called when a setup suite is being skipped.
      Parameters:
        `aSetupSuite` - the suite being skipped
        `aReason` - the reason for the skipping

    - #### onSetupFinish

          public abstract void onSetupFinish​(SuiteDefinition aSetupSuite,
                                             SuiteResult aResult)

      Called when a setup suite has been executed.
      Parameters:
        `aSetupSuite` - the setup suite that was executed
        `aResult` - the result of the execution

    - #### onTestStart

          public abstract void onTestStart​(Test aTest)

      Called right before a test is being executed.
      Parameters:
        `aTest` - the test

    - #### onTestFinish

          public abstract void onTestFinish​(Test aTest,
                                            TestResult aResult)

      Called after a test was executed.
      Parameters:
        `aTest` - the test that was executed
        `aResult` - the result of the execution

    - #### onTableTestStart

          public abstract void onTableTestStart​(TableTest aTableTest)

      Called when a table test is about to be executed.
      Parameters:
        `aTableTest` - the table test

    - #### onTableTestRowStart

          public abstract void onTableTestRowStart​(TableTest aTableTest,
                                                   TableTestRow aRow)

      Called when a single row of a table test is about to be executed.
      Parameters:
        `aTableTest` - the table test that contains the row
        `aRow` - the row

    - #### onTableTestRowFinish

          public abstract void onTableTestRowFinish​(TableTest aTableTest,
                                                    TableTestRow aRow,
                                                    TestSubResult aSubResult)

      Called after a table test row has been executed.
      Parameters:
        `aTableTest` - the table test that contains the row
        `aRow` - the row that was executed
        `aSubResult` - the result of the execution

    - #### onTableTestFinish

          public abstract void onTableTestFinish​(TableTest aTableTest,
                                                 TestResult aResult)

      Called after a tabletest was fully executed (all rows have been executed).
      Parameters:
        `aTableTest` - the table test
        `aResult` - the result of the test execution

    - #### onCallStart

          public abstract void onCallStart​(Call aCall)

      Called before a call is being executed.
      Parameters:
        `aCall` - the call

    - #### onCallFinish

          public abstract void onCallFinish​(Call aCall,
                                            CallResult aResult)

      Called right after a call was executed.
      Parameters:
        `aCall` - the call
        `aResult` - the result of the execution

    - #### onTearDownStart

          public abstract void onTearDownStart​(SuiteDefinition aTearDownSuite)

      Called before a teardown suite is being executed.
      Parameters:
        `aTearDownSuite` - the suite to be executed

    - #### onTearDownSkipped

          public abstract void onTearDownSkipped​(SuiteDefinition aTearDownSuite,
                                                 SuiteSkipReason aReason)

      Called when a teardown suite is being skipped.
      Parameters:
        `aTearDownSuite` - the suite being skipped
        `aReason` - the reason for the skipping

    - #### onTearDownFinish

          public abstract void onTearDownFinish​(SuiteDefinition aTearDownSuite,
                                                SuiteResult aResult)

      Called after a teardown suite was executed.
      Parameters:
        `aTearDownSuite` - the suite that was executed
        `aResult` - the result of the execution

    - #### onSuiteFinish

          public abstract void onSuiteFinish​(Suite aSuite,
                                             SuiteSummaryResult aResult)

      Called after a suite has finished execution. This might return a `SuiteResult` instance if the suite was executed locally, or a `SuiteSummaryResult` with just the summary count information if the suite ran on a fork, in which case the detailed information is not available.
      Parameters:
        `aSuite` - the suite that was executed
        `aResult` - the result of the execution

    - #### onExecutionFinish

          public abstract void onExecutionFinish​(TestModel aModel,
                                                 SuiteSummaryResult aResult)

      Called after all execution has been finished. This is always the last call of an execution phase.
      Parameters:
        `aModel` -
        `aResult` -

    - #### onVariableDefinition

          public abstract void onVariableDefinition​(VariableEntity aDefinition,
                                                    SuiteDefinition aSuite,
                                                    Object anInitialValue)

      Called when a variable is being defined.
      Parameters:
        `aDefinition` - the variable
        `aSuite` - the suite in which the variable is scoped (may be null if the variable is global)
        `anInitialValue` - the initial value (may be null if no initial value is given)

    - #### onConstantDefinition

          public abstract void onConstantDefinition​(ConstantEntity aDefinition,
                                                    SuiteDefinition aSuite,
                                                    Object aValue,
                                                    boolean aParameterizedFlag)

      Called when a constant is being defined.
      Parameters:
        `aDefinition` - the constant
        `aSuite` - the suite in which the constant is scoped (may be null if the constant is global)
        `aValue` - the value (may be null if no value was given)
        `aParameterizedFlag` - true if the constant was parameterized (value defined not in script, but from outside the test runner via parameter)

    - #### onVariableAssignment

          public abstract void onVariableAssignment​(VariableAssignment anAssignment,
                                                    VariableEntity aDefinition,
                                                    SuiteDefinition aSuite,
                                                    Object aValue)

      Called when a variable is being assigned.
      Parameters:
        `anAssignment` - the assignment
        `aDefinition` - the variable that the value is to be assigned
        `aSuite` - the suite in which the variable is scoped (may be null if the variable is global)
        `aValue` - the value

    - #### onReturnVariableAssignment

          public abstract void onReturnVariableAssignment​(SuiteReturn aReturn,
                                                          VariableEntity aSource,
                                                          VariableEntity aTarget,
                                                          Suite aSuite,
                                                          Object aValue)

      Called when a return variable value from a suite is assigned to the respective local variable in the calling suite.
      Parameters:
        `aReturn` - the return variable object
        `aSource` - the source variable entity
        `aTarget` - the target variable entity
        `aSuite` - the suite invocation for which the assignment is done
        `aValue` - the value to be assigned

    - #### onTimeSetStart

          public abstract void onTimeSetStart​(TimeSet aTimeSet,
                                              SuiteDefinition aSuite,
                                              List<ForkDefinition> someForks)

      Called when the test time will be set.
      Parameters:
        `aTimeSet` - the time to be set
        `aSuite` - the suite in which the time was set
        `someForks` - the forks on which the time was set (the null element in the list means the master process)

    - #### onTimeSetFinish

          public abstract void onTimeSetFinish​(TimeSet aTimeSet,
                                               TimeSetResult aResult)

      Called when the test time was set.
      Parameters:
        `aTimeSet` - the time to be set
        `aResult` - the result of the operation

    - #### onVisibleComment

          public abstract void onVisibleComment​(String aCommentText,
                                                boolean anIsTitle,
                                                VisibleComment aCommentElement)

      Called when a visible comment is encountered during execution.
      Parameters:
        `aCommentText` - the text inside the comment
        `aCommentElement` - the raw comment element

    - #### onVisibleDivider

          public abstract void onVisibleDivider​(String aDividerText,
                                                VisibleDivider aDividerElement)

      Called when a visible divider is encountered during execution.
      Parameters:
        `aDividerText` - the divider text (basically a String of '-' chars with minimum length of 3 chars)
        `aDividerElement` - the raw divider element

    - #### onMessageFromFork

          public abstract void onMessageFromFork​(TestRunnerCallbackMethods aMethod,
                                                 Serializable... someObjects)

      Called when a fork has sent a message to the masters' callback. In order to merge results determined by forks seamlessly into the masters' results, callbacks do automatically have a simple messaging system at their disposal. When a fork callback uses `sendToMaster(TestRunnerCallbackMethods, Serializable...)`, this method is called on the masters' respective callback in order to deliver the objects given.
      Parameters:
        `aMethod` - the method that was called on the forks' callback (doesn't have to be used, evaluating this parameter is the job of the masters' callback and can thus be omitted if it ain't necessary)
        `someObjects` - the objects sent by the forks' callback

    - #### onAbortExecution

          public abstract void onAbortExecution​(String anAbortExecutionMessage,
                                                String anAbortExecutionStackTrace)

      Called when test execution is aborted prematurely due to an `AbortExecutionException` - either thrown locally or by a fork. The original exception can't be provided since it cannot be received from a fork by remoting. Instead, the data from the exception is provided in both cases.
      Parameters:
        `anAbortExecutionMessage` - the message from the exception
        `anAbortExecutionStackTrace` - the stack trace of the exception

    - #### setRemotingServer

          public void setRemotingServer​(IntegrityRemotingServer aRemotingServer)

    - #### setDryRun

          public void setDryRun​(boolean aDryRun)

    - #### isFork

          public boolean isFork()

    - #### isDryRun

          public boolean isDryRun()

    - #### setForkInExecution

          public void setForkInExecution​(ForkDefinition aFork)

    - #### getForkInExecution

          public ForkDefinition getForkInExecution()

    - #### sendToMaster

          protected void sendToMaster​(TestRunnerCallbackMethods aMethod,
                                      Serializable... someObjects)

      When a callback that is running inside a fork instance uses this method, the given objects and the method parameter are being sent to the respective callback instance on the master. This mechanism is designed to allow for seamless integration of fork results into the masters' results.
      Parameters:
        `aMethod` - the method that was executed (doesn't have to be used, since the callback itself is responsible to parse this value)
        `someObjects` - the objects to be sent

    - #### receiveFromFork

          public void receiveFromFork​(String aCallbackClassName,
                                      TestRunnerCallbackMethods aMethod,
                                      Serializable[] someData)

      This method is used by the test runner to forward messages received from the forks to the callback.
      Parameters:
        `aCallbackClassName` - the callback class name
        `aMethod` - the method called
        `someData` - the objects given by the fork