Starting expecco via Command Line/rest/en

expecco REST Service Interface

If enabled, expecco accepts REST requests, via the URL "/expeccoService/rest". I.e. the default URL is "host:9090/expeccoService/rest".

Start expecco with REST Server enabled

The service can be started using the command line arguments -- server or --service. Please refer to the detailed description of the command line arguments for more details. Otherwise it is possible to start the service within the expecco IDE. In the Main Menu you will find the menu entries "Extras/Webservices/Test Execution Client For expeccoALM (SOAP)" Start... and Stop. The menu entry "Start" opens a dialog where you can choose the port number should be used by the server. If you choose start the SOAP and REST Services will be started. With the menu entry "Stop" the server will be stopped.

Introduction

The expecco REST service supports nearly the same set of operations as the expecco SOAP service, but uses a much more lightweight approach in its parameter encoding. It is both easier to implement on the client side, and also faster than SOAP, due to the minimal encoding/decoding overhead. Expecco REST calls are HTTP-GET or HTTP-PUT requests, possibly with attached JSON encoded argument data. For requests with response data, the data are also JSON encoded. The http response code on success is 200.

The operation is determined by the URI: the last component is the operation name to be executed.

A description of the supported REST calls can be aqcuired from the running service via "host:9090/expeccoService/rest/protocolInfo".

API Functions

A very useful REST-entry is the "protocolInfo" request, which returns a description of all supported REST call entries:

ProtocolInfo Request

"host:9090/expeccoService/rest/protocolInfo"

All REST services from eXept products support the protocolInfo request (see also expeccoALM-Rest service). It allows for a client to dynamically adapt to newer versions.

The Response is a JSON dictionary with the following fields:

• "Protocol" - an array containing one entry per supported call entry (see below).
• "URLPath" - the URL of the service (just a confirmation, as you would not have a response at hand without it)
• "Service" - the name of the service (class name in Smalltalk) currently always "ExpeccoRestService"
• "Version" - a protocol version number; currently 1

the elements of the protocol array are objects with the following fields:

• "Name" - the name of the rest call entry
• "Request" - the type of HTTP request, one of "GET","PUT" or "DELETE";
• "Comment" - a comment describing the operation
• "Argument" - a short description of the argument; if not present, argument is required; can be one of "Dictionary", "String" or any other of the basic JSON data types.
• "Return" - the type of return data. Same possible values as the argument description.

For example, the current expecco implementation returns the following JSON object:

{
    "Version":2,
    "URLPath":"expeccoService/rest",
    "Protocol":[
        {
            "Name":"cleanupTempFiles",
            "Request":"GET",
            "Comment":"remove leftover temporary files."
        },
        {
            "Name":"download",
            "Request":"PUT",
            "Comment":"download a suite.",
            "Argument":"(SuiteID:String, Suite:String, SuiteURI:String, Parameters:Array),"
        },
        {
            "Name":"execute",
            "Request":"PUT",
            "Comment":"start execution; return ticketID.",
            "Return":"Dictionary",
            "Argument":"(ID:String, SuiteID:String, Suite:String, SuiteURI:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
        },
        {
            "Name":"executeTestSuiteFile",
            "Request":"PUT",
            "Comment":"start execution of a well known suite; return ticketID.",
            "Return":"Dictionary",
            "Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
        },
        {
            "Name":"executeTestSuiteFileWithTestplanNames",
            "Request":"PUT",
            "Comment":"start execution of a well known suite; return ticketID.",
            "Return":"Dictionary",
            "Argument":"(ID:String, SuiteFileName:String, Environment:Dictionary, TestPlans:Array, Resources:Array, Parameters:Array)"
        },
        {
            "Name":"getExecutionInfo",
            "Request":"PUT",
            "Comment":"get execution status of an execute job; argument is ticketID.",
            "Return":"Dictionary",
            "Argument":"(ID:String)"
        },
        {
            "Name":"getListOfTestSuiteFiles",
            "Request":"GET",
            "Comment":"get a list of known test suites which can be executed via executeTestSuiteFile.",
            "Return":"Array"
        },
        {
            "Name":"killExecution",
            "Request":"GET",
            "Comment":"kill execution of an execute job; argument is ticketID.",
            "Argument":"(ID:String)"
        },
        {
            "Name":"loadSuite",
            "Request":"PUT",
            "Comment":"load a suite.",
            "Argument":"(SuiteID:String, SuitePathString:String, Parameters:Array),"
        },
        {
            "Name":"ping",
            "Request":"GET",
            "Comment":"test reachability and return some status info.",
            "Return":"Dictionary"
        },
        {
            "Name":"removeTicket",
            "Request":"GET",
            "Comment":"give up execution of an execute job; if required, kill the job. argument is ticketID.",
            "Argument":"(ID:String)"
        },
        {
            "Name":"waitForExecutionResult",
            "Request":"PUT",
            "Comment":"get execution status of an execute job; argument is ticketID.",
            "Return":"Dictionary",
            "Argument":"(ID:String; ReportFiles:Array,)"
        },
        {
            "Name":"protocolInfo",
            "Request":"GET",
            "Return":"Dictionary"
        }
    ],
    "Service":"ExpeccoRestService"
}

Test Execution

Execution by Suite File Name Request

"host:9090/expeccoService/rest/executeTestSuiteFileWithTestplanNames"

With this request you can execute suites which are already present on the execution slave. For this, expecco should be started with a "--suiteDirectory" option, which specifies the folder name, where common test suites are located.

If successful, a ticketID (the given job id) is returned.

The argument is a JSON object with the following fields:

• ID - mandatory; job id
• SuiteFileName - name of the testSuite file (ets file)
• Environment - optional
• TestPlans - optional
• Resources - optional
• Parameters - optional

The ID is an unique identifier which can be used later to retrieve the execution state, results and execution logs. The ets file must be present/reachable by the expecco slave. It may be either an absolute pathname (typically on a shared network drive) or a relative filename. If a relative file name is given, it will be searched in the folder specified with the "--suiteDirectory" command line argument.

{
    "ID":"Testrun-4713", 
    "SuiteFileName":"E:\\tmp\\DemoTest2.ets",
    "Environment":[
        "TestDelay1" "60"
    ],
    "TestPlans":[
        "DefaultTestplan"
    ], 
    "Resources":[], 
    "Parameters":[
        "generateLog" "true" 
        "generatePDFReport" "true"
    ]
}

Execute Request

"host:9090/expeccoService/rest/execute"

As described in the SOAP interface, expecco caches downloaded suites in a temporary cache folder. Therefore, the SuiteID field must be present and contain the test suite's ID.

The .ets file can be either passed down as data (in the Suite field), or expecco can be ordered to fetch the suite via http from the given SuiteURI. If Suite is empty or missing, expecco tries to fetch the .ets file via the SuiteURI. If both fields are empty, expecco will run the test if and only if the suite is already present in its cach folder. Thus, you can optimize execute requests, by either always provide a SuiteURI (instead of the suite data), or - if the client cannot provide the suite via HTTP, but has to send it as data - by first sending an execute request with only the suiteID, but neither suite-data, nor suite-URI. In this case, an error will be reported by expecco if it has the suite not already in its cache, and the client should send another execute request, this time with valid suite data.

The optional "Parameters" field:

If the "Parameters" field is present, it must be a JSON array containing alternating key-value elements. Currently supported keys are:

• "generateLog" - JSON boolean as corresponding value element
• "generatePDFReport" - JSON boolean as corresponding value element

The optional "TestPlans" field:

If the "TestPlans" field is present, it must be a JSON array containing JSON arrays as elements. Each entry must consist of a 1 or 2 element JSON array. The first being the UUID of the testplan, the optional second element must be (if present) another JSON array giving the list of test-case UUID to execute.

As described above, the returned object contains the job ID, which is used to refer to this execution job in further getExecutionInfo or terminateExecution requests (see below).

The argument is a JSON object with the following fields:

• ID - mandatory; job id
• SuiteID - mandatory; the UUID of the test suite
• Suite - optional; suite data file (ets file) in base64 encoding
• SuiteURI - optional; the URL where expecco could fetch the suite
• Environment - optional;
• TestPlans - optional;
• Resources - optional
• Parameters - optional;

Status Request

"host:9090/expeccoService/rest/getExecutionInfo"

This query returns status information about an ongoing execution. Its single parameter field must contain a ticketId as described in the execute request.

The argument is a JSON object with the following fields:

• ID - mandatory; job id

Terminate/Abort Request

"host:9090/expeccoService/rest/killExecution"

Use this, to abort and terminate an ongoing test execution.

The argument is a JSON object with the following fields:

• ID - mandatory; job id

Remove Ticket Request

"host:9090/expeccoService/rest/removeTicket"

Use this, to tell expecco, that no further interest exists in a ticket. If the test is still running, it is aborted. If it is about to be started, it will not be. Any temporary files which might have already been created due to this execution are removed.

The argument is a JSON object with the following fields:

• ID - mandatory; job id

Cleanup of Old Result/Log Files

"host:9090/expeccoService/rest/cleanupTempFiles"

This request can be used to remove all temporary files, especially leftover report- and log files. This should be used, if a client has crashed, and lost track of

No argument. no return value.

Ping Request

"host:9090/expeccoService/rest/ping"

This request answers with information about the host, architecture, disk usage and other status about the machine on which expecco is running. Also, a list of available plugins on the target machine is returned. Of course, it is also useful to see if the expecco service is ready and the communication works as expected.

No argument. Returns an object containing status information.

Download Request "/expeccoService/rest/download"

This is similar to the suite transmission scheme described in the execute request. However, the suite is not executed. The argument is a JSON object with the following fields:

• SuiteID - mandatory String; the suite's ID
• Suite - optional String; base64 encoded .ets file
• SuiteURI - optional String; the URI from which expecco can fetch the suite
• Parameters - optional Array. For future expansion

The operation is the same as described in the previous SOAP section.

Examples

Example Requests / Responses

Wire protocol of sending a Ping request ("/expecco/rest/ping"):

Request to expecco:

 GET /expeccoService/rest/ping HTTP/1.1 
 Host: localhost:9123 
 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0 
 Accept: application/json 
 Connection: keep-alive 

Response:

 HTTP/1.1 200 OK 
 Content-Type: application/json; charset="utf-8" 
 Content-Length: 4111 
 Connection: Keep-Alive 

 {
    "hello":"exeptn.bh.exept.de",
    "restInterfaceVersion":"1",
    "node":"fancy",
    "osType":"osx",
    "cpuType":"x86_64",
    "osRelease":"10.8.0",
    "architecture":"Darwin",
    "system":"Darwin"
    "numberOfCPUs":4,
    "numberOfRunningTests":0,
    "suiteDirectories":["/Users/cg/work/exept/expecco/projects"],
    "knownTestSuites":["test1.ets","test2.ets"],
    "expeccoRelease":"2.7.0.0",

    "pluginNames":["SwiftMessages","WSDL Import Support","XMI Import Support","RemoteAccess",
                  "SAP  Plugin","DotNET Bridge","SWT GUI Test Plugin","JavaFX GUI Test Plugin","VNC Client",
                  "Android GUI Testing Plugin","SNMP Plugin","Windows Automation Plugin","Manual Test Import 2",
                  "Windows Forms Plugin","Java Browser","Visual Basic Scripting","Swing GUI Test Plugin","Java Import",
                  "Java Bridge","QtTesting","C Header File Parser (DLL Call Generator)","Java Debugger",
                  "Common Java GUI Test Plugin","JIRA Interface","SmallSensePlugin","DocuPrintPlugin","Webtest (Selenium)",
                  "Gembird Power Manager Control","GUI Testing Plugin Platform","EDI-Edifact"],
    "plugins"[...],
    "expeccoPluginID:DLLCallGeneratorPlugin":"e79207a0-0c23-11df-8eaf-00ff7b08316c 1 1.24",
    ...
    "expeccoPluginID:VBScriptPlugin":"09a8d100-eb01-11e3-9aba-6067202bc199 1 1.25",

}

Download request to expecco (without suite-info, to check if the suite is already loaded):

 GET /expeccoService/rest/download HTTP/1.1 
 Host: localhost:9123 
 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0 
 Accept: application/json
 Connection: keep-alive

 {
   "SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}

Response (empty, because suite is not present):

 HTTP/1.1 200 OK 
 Content-Type: application/json; charset="utf-8" 
 Content-Length: 4111 
 Connection: Keep-Alive 

 {
}

Download request to expecco (with suite-info, to ensure suite is present):

 GET /expeccoService/rest/download HTTP/1.1 
 Host: localhost:9123 
 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0  
 Accept: application/json 
 Connection: keep-alive

 {
   "SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
   "Suite":"... base64 encoded .ets suite file ..."
}

Response (non-empty, because suite is now present on the expecco client machine):

 HTTP/1.1 200 OK 
 Content-Type: application/json; charset="utf-8" 
 Content-Length: 4111 
 Connection: Keep-Alive 

 {
   "SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
}

Execute request to expecco (with suite-info). The suite info is not required, if the above download was done before.

 GET /expeccoService/rest/execute HTTP/1.1 
 Host: localhost:9123 
 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0 
 Accept: application/json 
 Accept-Language: en-US,en;q=0.5 
 Accept-Encoding: gzip, deflate 
 Connection: keep-alive

 {
   "ID":"09ab0149-1234-9876-4583-1259a5e301f5",
   "SuiteID":"09a8d1FF-ebF1-12AB-9aba-98ab016389f0",
   "Suite":"... base64 encoded .ets suite file ..."
}

Response (returns the execution's job ID):

 HTTP/1.1 200 OK 
 Content-Type: application/json; charset="utf-8" 
 Content-Length: 4111 
 Connection: Keep-Alive 

 {
   "ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}

Get progress and status information about a running test:

 GET /expeccoService/rest/getStatusInfo HTTP/1.1 
 Host: localhost:9123 
 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0 
 Accept: application/json 
 Accept-Language: en-US,en;q=0.5 
 Accept-Encoding: gzip, deflate 
 Connection: keep-alive

 {
   "ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}

Response (returns the execution's job ID):

 HTTP/1.1 200 OK 
 Content-Type: application/json; charset="utf-8" 
 Content-Length: 4111 
 Connection: Keep-Alive 

 {
   "ID":"09ab0149-1234-9876-4583-1259a5e301f5",
}

Alternative execute-by-filename request (the suite-file must be present on the slave already):

 GET /expeccoService/rest/executeTestSuiteFile HTTP/1.1 
 Host: localhost:9123 
 User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.6; rv:35.0) Gecko/20100101 Firefox/35.0 
 Accept: application/json 
 Accept-Language: en-US,en;q=0.5 
 Accept-Encoding: gzip, deflate 
 Connection: keep-alive

 {
   "ID":"09ab0149-1234-9876-4583-1259a5e301f6",
   "SuiteFileName":"c:\sharedSuites\test.ets"
}

Perl Client

use REST::Client;
use JSON;
# Data::Dumper makes it easy to see what the JSON returned actually looks like 
# when converted into Perl data structures.
use Data::Dumper;
use MIME::Base64;

my $username = 'admin';
my $password = 'admin';
my $headers = {Accept => 'application/json', Authorization => 'Basic ' . encode_base64($username . ':' . $password)};
my $client = REST::Client->new();
$client->setHost('http://127.0.0.1:9090');

#parameter for start test Request
my $startTestURL = '/expeccoService/rest/executeTestSuiteFileWithTestplanNames';
my $startTestJSONArguments = '{ "ID":"expeccoRemoteExec" "SuiteFileName":"E:/exept/tmp/SimpleBridgeTest.ets" "TestPlans":[ "Demo Testplan" ] "Parameters":[ "generateLog" "true" ]}';

#parameter for wait for test end and generate results Request
my $waitTestEndAndCreateResultURL = '/expeccoService/rest/waitForExecutionResult';
my $waitTestEndAndCreateResultJSONArguments = '{"ID":"expeccoRemoteExec" "ReportFiles":[ {"JUnit_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.junit"} {"PDF_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.pdf"} {"TEXT_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.txt"} {"HTML_ReportFile":"E:/tmp/logs/SimpleBridgeTestResult.html"} ]}';


$client->request('PUT', $startTestURL, $startTestJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
     print "\n=== Test started ===\n";
     #my $response = from_json($client->responseContent());
	 #print Dumper($response);
} else {
	print Dumper($client->responseContent());
}

$client->request('PUT', $waitTestEndAndCreateResultURL, $waitTestEndAndCreateResultJSONArguments, $headers);
if( $client->responseCode() eq '200' ){
     print "\n=== Test execution and result generation finished ===\n";
     #my $response = from_json($client->responseContent());
	 #print Dumper($response);
} else {
	print Dumper($client->responseContent());
}

---

Copyright © 2014-2024 eXept Software AG