LISA Invoke

Document ID : KB000019233
Last Modified Date : 21/06/2018
Show Technical Document Details
Introduction:

LISA Invoke

Please note: The information contained here remains valid, however LISA Invoke has been superseded by an alternative REST interface - the REST Invoke API. Please see the documentation for your release, and, the documentation here and the examples here.

Background:

The lisa-invoke was built to provide a zero dependency REST like invocation mechanism for LISA tests and suites. The initial deployments were used to integrate with 3rd party products like CentraSite, MKS and SOA Software's PolicyManager. Currently LISA Invoke has been modified to be deployed as part of LISA and hosted in the in-process instance of Jetty. This gives us the ability to allow a user to invoke a test through a URL on any instance. Tests can be invoked either synchronously or asynchronously. The synchronous invocation will return back an XML payload that includes cycle history information as well as a link to an HTML formatted report. The asynchronous invocation will return back a XML payload that contains a callback key. The callback key can then be used to check the status of the test. In addition to checking the status, you can also stop or kill a long running test.

 

Instructions:

Lisa-Invoke has some configuration requirements. The properties specific to lisa-invoke that are used by default are located in the lisa.properties file located in LISA_HOME. The following properties are used in the configuration of Lisa-Invoke:

  • lisa.portal.invoke.base.url=/lisa-invoke
  • lisa.portal.invoke.report.url=/reports
  • lisa.portal.invoke.server.report.directory={{lisa.tmpdir}}{{lisa.portal.invoke.report.url}}
  • #lisa.portal.invoke.test.root={{LISA_HOME}}

In addition to these properties, there are properties that are used that are also used by other Jetty processes:

  • lisa.portal.url.prefix
  • lisa.webserver.port

Usage

Run tests with: /lisa-invoke/runTest?testCasePath=testCasePath&stagingDocPath=stagingDocPath&[configPath=configPath]&[async=true]

The parameters used are:

  • testCasePath - required - path relative to the registry for the test case to run.
  • stagingDocPath - optional - path relative to the registry for the run doc to be used. If none is supplied a default run doc will be created and used with default report generator.
  • configPath - optional - path relative to the configuration to be used. If none is supplied then the project's project.config will be used.
  • coordinatorName - optional - the name of the coordinator attached to the registry which will be used to stage the test. If none is supplied then the default coordinator name (lisa.csName) will be used. If no default name is found an exception will be thrown and the error returned to the client.
  • async - optional - Defaults to false. If true will return a callback key that can then be used to get back status or stop / kill a test.
  • addTestInfo - defaults to false. If true will return a list of tests for pass, fail and errored tests.
  • legacyReporting - optional - Defaults to false. If true will create a 4.5 style invoke report. Basically an HTML report that was constructed from the TestResultsEventListener object used in the test. Otherwise the report will be housed in the 5.0 reporting portal if the staging document includes a report generator.

To use the callbackKey returned back to the caller, invoke the callback service.

/lisa-invoke/callback?testCasePath=[testCasePath]&callbackKey=[callbackKey]&command=[status|kill|stop]

The parameters used are:

  • testCasePath
  • callbackKey
  • command
  • must be one of the following 3 values:
    • status - will return back a response either indicating that the test is still running or the report generated by the test execution.
    • kill - will hard kill a test.
    • stop

Understanding the Response

The XML response is fairly simple but can vary based on the parameters passed in or the state of the test at any given point. This section describes what you can expect to see.

method Node

The method node has a 'name' attribute that will have a name of the method being invoked. The 'method' node also have a child node named 'params'. The params node has multiple 'param' nodes each containing a name and value. These are the parameters that were passed into the method.

status Node

The status node is the status of the call. The call was either 'OK' or there was an 'ERROR'.

result Node

The result Node contains information on the result of the call. This is the section with the most variance in its contents. The possible children elements are as follows:

  • status - the status of a test case being run. Possible values are RUNNING or ENDED
  • reportUrl - this is the url to the report in the reporting server. Currently this url takes you to the function report print preview page. Eventually there will be support to take you to the report in the reporting portal so that further analysis can be done. If the invocation is done with legacyReport parameter = true then you will see a link to an HTML formatted report.
  • callbackKey - this is a uid that is assigned to each call. It will only be shown if 'async' = true and can be used to retrieve information from the callback service.
  • runId - this is the Run Unique Id that is assigned to the test run. It represents the unique id of the test run.
  • pass - this node will contain an attribute, "count" with the value of count being how many tests passed. It may be an empty node. When "addTestInfo" is true it will have a list of child elements that represent the tests.
  • fail - similar to pass but with the tests that failed.
  • warning - similar to pass but with the tests that threw warnings.
  • error - similar to pass but with the tests that threw errors.
  • message - this is a field that will contain a message pertinent to the run. For instance, if the status Node were to be an ERROR, you would expect to find details of the error here. If it is an async test run then you may expect to find the time and date of the async invocation. If it was a status call and the test was still running you would see some messaging here.

Sample Calls

This section contains sample results for calls that are made to lisa-invoke.

Sync Call

<?xml version="1.0" encoding="UTF-8"?>
<invokeResult>
<method name="RunTest">
<params>
<param name="stagingDocPath" value="D:\LisaTests\LisaInvoke\StagingDocs\RunOnce.stg" />
<param name="legacyReport" value="false" />
<param name="coordName" value="lisa.CServer" />
<param name="configPath" value="D:\LisaTests\LisaInvoke\Configs\project.config" />
<param name="testCasePath" value="D:\LisaTests\LisaInvoke\Tests\ExecuteFromLISAInvoke.tst" />
<param name="callbackKey" value="30653934383432362D363838352D3464" />
</params>
</method>
<status>OK</status>
<result>
<status>ENDED</status> <reportUrl><![CDATA[http://192.168.171.25:1505/reporting/printPreview_functional.html#Idstr=33306330363137392D363330632D3430&curtstr=T]]></reportUrl>
<runId>33306330363137392D363330632D3430</runId>
<passCount>1</passCount>
<failCount>0</failCount>
<warningCount>0</warningCount>
<errorCount>0</errorCount>
<message>ExecuteFromLISAInvoke,Run Once</message>
</result>
</invokeResult>

Async Call

<?xml version="1.0" encoding="UTF-8"?>
<invokeResult>
<method name="RunTest">
<params>
<param name="stagingDocPath" value="LisaInvoke/StagingDocs/RunOnce.stg" />
<param name="legacyReport" value="false" />
<param name="coordName" value="" />
<param name="configPath" value="LisaInvoke/Configs/project.config" />
<param name="testCasePath" value="LisaInvoke/Tests/ExecuteFromLISAInvoke.tst" />
<param name="callbackKey" value="31616536303561332D633765302D3439" />
<param name="async" value="true" />
</params>
</method>
<status>OK</status>
<result>
<callbackKey>31616536303561332D633765302D3439</callbackKey>
<message>The LISA test 'LisaInvoke/Tests/ExecuteFromLISAInvoke.tst' was launched asynchronously at Wed Sep 15 10:44:17 CDT 2010.</message>
</result>
</invokeResult>

Stop / Kill Call

<?xml version="1.0" encoding="UTF-8"?>
<invokeResult>
<method name="RunTest">
<params>
<param name="command" value="stop" />
<param name="testCasePath" value="LISAInvoke\Tests\ExecuteFromLISAInvoke.tst" />
<param name="callbackKey" value="30356666393366362D383937372D3431" />
</params>
</method>
<status>OK</status>
<result>
<status>RUNNING</status>
<message>Test has been scheduled to stop or killed.</message>
</result>
</invokeResult>

Status Call

<?xml version="1.0" encoding="UTF-8"?>
<invokeResult>
<method name="RunTest">
<params>
<param name="command" value="status" />
<param name="testCasePath" value="LISAInvoke/Tests/ExecuteFromLISAInvoke.tst" />
<param name="callbackKey" value="31616536303561332D633765302D3439" />
</params>
</method>
<status>OK</status>
<result>
<status>RUNNING</status>
<message>The Test is still running. Please check back.</message>
</result>
</invokeResult>

Additional Information:
The LISA invoke API has been succeeded by a REST API. Please the  documentation here and the examples here.