Package com.mks.tm.api.spi

Interface ITestSessionAdapter

public interface ITestSessionAdapter

An interface for all concrete tests via an external automated testing tool. Implementations of this interface translate a test session and related ordered test case items to a set of invocations of external automated tests as well as the mapping of the results from these external automated tests to test results in PTC RV&S Test.

A class implementing this interface can be installed on the PTC RV&S Agent by defining a mapping between the external name for the adapter and the implementation class name in the tm.properties file. The mapping property is of the form:
tm.adapter.<adapterName>.class=<adapterClassName>

The implementation class and any supporting classes need to be installed on the PTC RV&S Agent. If the adapter implementation is packaged into a .jar files it can be installed by copying the .jar files into the <installation root>/data/java/jars directory. If the adapter implementation is not packaged then the directory tree of .class files and other resources can be installed by copying the directory tree under the <installation root>/data/java/classes directory.

Requests from the PTC RV&S Server (via the 'imAgentBean' runTestSession method) result in the PTC RV&S Agent loading the implementation class via the external adapter name. If the implementation class is successfully loaded then then the initialize() method will be called. This provided the test session adapter implementation an opportunity to configure itself for running the test session and performing validation of the test session. Note that this validation should not take a long period of time as this will block the post trigger event on the server for the duration of the initialization. Once initialization is complete the post trigger event will continue.

If the initialize() method succeeds (does not throw an exception), the test session execution will be started and the execute() method will be called. At this point the test session adapter implementation is responsible for execution of the test cases that compose the test session and translating the results of the test cases in the external testing tool into test results.

During the initialize(), execute() or uninitialize() operations the test session adapter implementation may be requested to cancel the test session run (via the 'imAgentBean' cancelTestSession method or as a result of the PTC RV&S Agent shutting down) result in the cancel() method being called. The test session adapter implementation should at the very least not execute any further tests and ideally would interrupt the test case execution currently in progress. Note that this cancellation mechanism does not interrupt the thread performing the initialize, execute() or uninitialize operation, such interruption is up to the test session adapter implementation of the cancel() method if it is appropriate. Note that cancellation should not take a long period of time as this will block the post trigger event on the server for the duration of cancellation. Once cancellation is complete the post trigger event will continue.

Finally, independent of how the test session terminates (failure, cancellation, or completion of the test execution) the uninitialize() method will be called. This provides the test session adapter implementation to release any resources it allocated and to shut down cleanly.

It is guaranteed that the initialize(), execute() and uninitialize() methods will all be called on the same thread and that cancel() will be called on a different thread unless the adapter implementation itself directly calls cancel().

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancel(ITestSessionRun testSessionRun)
    This method is called in the case where the test session execution is requested to be cancelled (via the as well as the 'imAgentBean' cancelTestSession method or as a result of the PTC RV&S Agent shutting down).
    void
    execute(ITestSessionRun testSessionRun)
    This method is called after the initialize method completes successfully.
    void
    initialize(ITestSessionRun testSessionRun)
    This method is called when the test session adapter is initially allocated, and is called before the execute or uninitialize methods.
    void
    uninitialize(ITestSessionRun testSessionRun)
    This method will be called at the end of the test session independent of the test session running to completion, cancellation or encountering an error.

  • Method Details

    • initialize

      void initialize(ITestSessionRun testSessionRun) throws Exception

      This method is called when the test session adapter is initially allocated, and is called before the execute or uninitialize methods.

      The intended use for this method is for the adapter to perform any tests session wide validation and resource allocation. If the test session adapter implementation detects that the test session itself or any related configuration is not adequate or is incorrect it should throw an exception to prevent the execute method from being called.

      Parameters:
      testSessionRun - The test session run providing context.
      Throws:
      Exception - In the event that the test session adapter implementation has detected that the test session or related configuration is not adequate or is incorrect. Throwing of an exception will prevent the execute method from being called.

    • execute

      void execute(ITestSessionRun testSessionRun) throws Exception

      This method is called after the initialize method completes successfully.

      The intended use for this method is for the adapter to inspect the test session and test cases that compose the test session and using this information map the test cases to concrete external test cases that are executed. The results of these external test cases should be translated into test results.

      Parameters:
      testSessionRun - The test session run providing context.
      Throws:
      Exception - In the event that the test session adapter implementation has encountered an error in translation, execution, or inspection of the test results for the concrete test cases.

    • cancel

      void cancel(ITestSessionRun testSessionRun) throws Exception

      This method is called in the case where the test session execution is requested to be cancelled (via the as well as the 'imAgentBean' cancelTestSession method or as a result of the PTC RV&S Agent shutting down).

      The intended use for this method is for the adapter to no longer start any new external tests and ideally interrupt any current external test case in progress.

      Parameters:
      testSessionRun - The test session run providing context.
      Throws:
      Exception - In the event the request to cancel the test session execution is not supported or failed for some reason.

    • uninitialize

      void uninitialize(ITestSessionRun testSessionRun) throws Exception

      This method will be called at the end of the test session independent of the test session running to completion, cancellation or encountering an error.

      The intended use for this method is for the adapter to release any test session wide resources that were allocated.

      Parameters:
      testSessionRun - The test session run providing context.
      Throws:
      Exception - In the event the test session adapter encountered an error.