Quelltext der Seite Starting expecco via Command Line/en

== Introduction ==

expecco can be started manually via the command line, by batch or shell scripts or automatically via the crontab (Unix) or scheduled tasks / services (Windows) mechanism of the operating system. Thus, you can have tests to execute unattended and without GUI "overnight". This is also the method to integrate expecco with other quality tools, such as Jenkins, HP-Quality Center, Polarion, expecco ALM etc.

Command line options allow for test suites to be loaded, executed and result files being generated without requiring user interaction.

In addition to the above, expecco can also be started in a slave mode as a service, to wait for incoming test-run request from a QM system, such as expecco ALM or Polarion. Expecco can respond to request via SOAP or REST calls to load, execute and report test suites. The expeccoNET automation environment assumes that expecco is already running on each slave host, and each has been started with a "--server" command line argument. It uses HTTP+SOAP/REST to communicate with those expecco slaves by default.

In this later "slave mode", expecco is installed to run as a daemon process (under Unix) or as a service (under Windows), and will be automatically started by the operating system, when it boots. The details of how it is installed vary between operating systems: under Unix, it needs to be registered in the init-tab-folder, under Windows it needs to be installed as a Windows service.

== Command Line ==

If expecco is started without command line arguments, it will open up showing the initial welcome screen. The same behavior as if started via the desktop.

With a single file argument, expecco will read a test suite from the given file and open an editor window on it (but will not execute it).

 '''expecco <testsuite filename>'''

This is the same behavior as if a test suite file (.ets) is dropped onto the expecco icon via the desktop.

The simplest command line to execute a test suite is:

 '''expecco --execute <testsuite filename> ...'''

:<testsuite filename> is the test suite's filename, as saved from within the expecco GUI application. This should be a saved ".ets" testSuite file. If more than one test suite filename is given, each is processed in sequence. All top-level test plans as found in the test suite(s) are executed (see below for more options).

:By default, the overall execution outcome is returned by the command's return value (exit code), which is
::0        - all PASSED
::non-zero - any ERROR, FAILURES or INCONCLUSIVE items.

The return value is useful if expecco is started via a makefile, or from Jenkins for example. If the caller needs a different exit code, use one of the exitCodeOnXXX options as described below. This is useful to avoid a ''make'' or ''jenkins'' process from stopping.

To get a list of available options, type:
 '''expecco --help'''


=== Command Line Options ===
Command line options are handled at two places: the runtime system (Smalltalk/X VM) and the expecco application itself.
When expecco is started, the VM is first to look for command line arguments and processes any of the VM options, until
a non-VM option is encountered. It passes the remaining options to expecco's main entry.
Thus, any option which is given after the first non-VM option will not be handled by the VM, but by expecco. Therefore, no VM options should be placed after the first non-VM option. VM options are marked as "''VM option''" in the list below.

Also, some options are specific to the operating system, on which expecco is executed. These are marked as "''Windows''", "''Linux''" etc.

=== Recommended Command Line Options ===

To start expecco on an existing test suite, use:

 '''expecco <testsuite filename>'''

this is also the way expecco is started, when a test suite file is double-clicked on the Linux or Windows desktop, or when a test-suite document is dropped onto the expecco icon.
The above opens the expecco GUI and loads the given test suite initially. However, it does not automatically execute any test.

To execute a suite, add a "'''--execute'''" argument (or in expecco 2.10, "-E"), as in:

 '''expecco --execute <testsuite filename>'''

You will notice, that expecco shows a banner initially; this can be disabled with a '''--noBanner''' option. Also, under windows, a small tray icon is shown in the lower right, which provides a controlling UI. This is disabled with '''--noTray'''.

Finally, as mentioned before, the test's outcome is reported via the exit code. If you want a little more information on the status of individual test cases, use a '''--verdicts''' option.

This makes the following a good start for your command line:

 '''expecco --noBanner --noTray --verdicts --execute <testsuite filename>'''

or, if you want to use a special parameter-file, to provide values for (some of) the project-variables:

 '''expecco --noBanner --noTray --verdicts --parameter &lt;param-file&gt; --execute &lt;filename&gt;'''

Parameter files are XML, CSV or JSON-files containing key-value pairs. They are usually created by saving an environment from within the expecco GUI (see [[Environment Editor]]).

All of the above command lines opened an expecco UI window.
To execute a suite without GUI, add a "'''--noWindow'''" argument.

To compose "scatter-gather" test cases from possibly multiple suites, found in a directory use:

 '''expecco --suiteDirectory &lt;dirName&gt; --testCaseNames "T01,T02,T05" --execute'''

or, to explicitly specify the suite-files where test cases are taken from, use:

 '''expecco --testCaseNames "T01,T02,T05" --execute &lt;suiteFile1&gt;.ets &lt;suiteFile2&gt;.ets ...'''

Finally, to get a report, add a "'''--xxxReportFile &lt;fileName&gt;'''" argument, as in:

 '''expecco --noBanner --noWindow --noTray --verdicts --parameter &lt;param-file&gt;''' \
 '''        --pdfReportFile result.pdf --execute &lt;filename&gt;'''

All options are described in more detail below.

=== Executing Multiple Test Suites in Sequence ===

It is possible to run multiple (possibly different) test suites with one command line to reduce startup and project loading times.
For this, provide multiple "--execute &lt;filename&gt;" arguments to the command line, as in:

 '''expecco --execute &lt;suiteFile1&gt;.ets --execute <suiteFile2&gt;.ets ...'''

with this command line, expecco first executes the toplevel testplan(s) from "suiteFile1.ets", then those from "suiteFile2.ets". All parameters (i.e. top-level variable values) will be taken from within the corresponding suite file.

To change individual parameters, use "--parameter:key=value" arguments before the corresponding --execute argument. For example, to execute the same suite with different parameters, use a command line like:

 '''expecco --parameter:device=samsung --execute mobileTest.ets''' \
 '''        --parameter:device=nexus --execute mobileTest.ets'''

=== Opening a Previous Result File ===

As described below, expecco can generate result files in various formats and different detail. The pdf, HTML and JUnit outputs will contain summary information to be read by humans, archived or to be passed to other programs (e.g. to Jenkins for statistics).

The native result file (.elf) contains all trace and logging information including the original test suite.

As such, it can be archived to ensure that the test result can always be associated to the exact suite being executed, even if the suite file is lost or has been modified in the meanwhile.

These .elf result files are generated either via corresponding command line options or manually via the "''Test Results''"-"''Save Result As...''" menu item.
Like regular suite files, they can be opened via the command line or via the "''File''"-"''Open...''" menu item.

When opened, the original suite (at the time of execution), the trace- and log data and the execution times will be presented. It is even possible to re-execute individual blocks, test plans or the whole suite.

This feature is very powerful, in that it allows for the result file to be given to a developer and will help to analyse the data values, control flows and even to rerun tests and reproduce errors/failures.

=== Detailed Option Description ===

==== Information/Debugging/Logging ====

*'''<code>--help</code>'''<br>Prints an up-to-date list of possible options and command line arguments.<p></p>

*'''<code>--version</code>'''<br>Prints the expecco release identification and exits.<p></p>

*'''<code>--noBanner</code>''' (''VM option'')<br>Suppress the splash startup banner.<p></p>

*'''<code>--console</code>''' (''VM option'', ''Windows only'')<br>Open a debug console window for Stdout and Stderr.<p></p>

*'''<code>--verbose</code>''' (''VM option'')<br>Additional startup, execution and result info is sent in human readable format to the stderr output. This is mainly meant to analyze startup problems and is actually more useful for expecco developers. It may be too much of printout, so try "''--verdicts''" instead.<p></p>

*'''<code>--debug</code>'''<br>Turns on startup debugging. By default, if an error occurs during startup, expecco terminates itself. With this option enabled, a command line debugger is opened instead. This is probably only useful for plugin developers.<p></p>

*'''<code>--silent</code>'''<br>Suppresses most info, warning and error messages which are sent to stderr/stdout. This is mainly meant to remove unwanted informational messages (for example, when plugins cannot be loaded during startup, etc.).<br>(this option is available with expecco vsn >= 2.10)<p></p>

==== Startup ====

*'''<code>--settings <fileName></code>'''<br>Force using <fileName> instead of the default "<code>~/.expecco/.expeccoPreferences</code>" to be used for the settings file name. Useful if you want different setups to be linked to different desktop icons, or to start expecco with particular settings from a batch or shell script. To generate a preferences file, open the "''Extras''" - ''Settings''" dialog, change the settings as required, and select the "''File''"-"''Save As...''" menu item.<p></p>

*'''<code>--licenseFile <fileName></code>'''<br>Use this license, instead of the default "<code>~/.expecco/.expeccoLicense</code>". If a license server (floating licenses) is used, the license server's hostname and port information is read from the settings file.<p></p>

*'''<code>--licenseServerHost <hostName></code>'''<br>Use this host as license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service).<br>(this option is available with expecco vsn >= 2.10)<p></p>

*'''<code>--licenseServerPort <portNr></code>'''<br>Use this port-nr when contacting the license server, instead of the one specified in the settings file (or if no settings file was ever specified). This may be needed when running expecco as a test slave (daemon or service).<br>(this option is available with expecco vsn >= 2.10)<p></p>

*'''<code>--noTray</code>''' (''Windows only'')<br>Disable the tray control icon (server and execute modes only).<p></p>

*'''<code>--tray</code>'''<br>Force a tray window to be shown, even if running in non-server (slave) mode. The tray window displays the current execution status, memory situation, thread status and other internal information, which is probably only useful for developers.<br>(this option is available with expecco vsn >= 2.10)<p></p>

*'''<code>--noWindow</code>'''<br>Do not open the main window (useful when scripting or executing only).<p></p>

*'''<code>--noDisplay</code>'''<br>Do not open any window (useful when scripting or executing only).<p></p>

*'''<code>--noPlugins</code>'''<br>Disable plugin loading. This makes startup somewhat faster, depending on the number of plugins found in your installation directory. You can still force individual plugins to be loaded using the "'''--loadPlugin'''" option. Use "''--noPlugins''" followed by a list of individual "''--loadPlugin''" options, to tune startup time with a minimum set of required plugins being loaded.<p></p>

*'''<code>--loadPlugin <pluginName></code>'''<br>Force loading a specific plugin. This is only useful if a "'''--noPlugins'''" option was given before. ''pluginName'' is the name of the folder in the "plugin" folder (under the expecco installation folder). Use "''--noPlugins''" followed by a list of individual "loadPlugin" options, to tune startup time with a minimum set of required plugins being loaded.<p></p>

*'''<code>--noUpdateCheck</code>'''<br>If configured by the user's settings, expecco automatically checks for updates and patches when started (by checking the eXept web-server for the presence of new patch files). This option disables that check, even if configured in the settings. Notice, that this is usually controlled by the user settings; however, in situations where settings are shared among multiple machines (network drive) and a test host has no (or should not have) internet access, it may be useful to disable this from the command line. It is especially useful, if you are disconnected from the Internet (isolated test-lab), to avoid time delays resulting from connection failures.<p></p>

*'''<code>--requireLogin</code>'''<br>Opens expecco in a (lightweight) multi-user mode, in which a username must be entered before the actual interaction with expecco begins. This user name will be used to load custom per-user settings (named "<code>.expeccoSettings_<name></code>") and will also be used in the generated reports. Also, the "''File''" menu will contain an additional "''Logout''" menu item, which brings back the initial login dialog.<br>This mode is useful, if expecco is used on a machine by multiple users, and expecco should remain opened (i.e. as a test stand). For example in a production floor, where tests are executed in multiple shifts by multiple operators.<p></p>

*'''<code>--load <fileName or packageName></code>'''<br>Loads a class file, extension or user plugin. The argument must be either the name of a Smalltalk source or binary file, or the name of a package (which must be found in the "<code>packages</code>" subfolder under the expecco installation folder). For details on how to generate such packages, read [[Creating_new_Class_Library_Packages/en | "Creating new Class Library Packages"]].

==== Test Execution ====
*'''<code>--execute &lt;fileName&gt;</code>'''<br>read and execute a suite. Starting with expecco 2.10, you can also use "-E &lt;fileName&gt;", which makes the command line a bit shorter.<p></p>

*'''<code>--execute</code>'''<br>without a filename, this should be the last argument of a scatter-gather dynamically generated suite command (see below: scatter-gather tests)<p></p>

==== Test Selection ====

the following options allow for individual test plans to be selected for execution from a suite which contains multiple test plans. Without any such option, ''--execute'' will run all top-level testplans found in the suite in sequence.

*'''<code>--testPlanName <namePattern></code>'''<br>Only execute test plans with a matching name.<br>For backward compatibility, "'''<code>--testSuiteName <namePattern></code>'''" is still supported and has the same effect.<p></p>

*'''<code>--testPlanTag <tagPattern></code>'''<br>Only execute test plans with a matching tag.<br>For backward compatibility, "'''<code>--testSuiteTag <tagPattern></code>'''" is still supported and has the same effect.<p></p>

*'''<code>--testPlanID <uuid></code>'''<br>Only execute that particular test plan (repeat to execute multiple test plans).<br>Starting with release 2.7, the following shortcut can also be used: '''<code>--testSuiteID "<uuid1>,<uuid2>,...,<uuidN>"</code>'''.<br>For backward compatibility, "'''<code>--testSuiteID <uuid></code>'''" is still supported and has the same effect.<p></p>

==== Scatter Gather Test Suite Composition ====

these options allow for a test plan to be composed out of a single or multiple of individual suite files. When composing, a new test plan is temporarily created, which contains the specified test cases. This is in contrast to the above options, where preexisting test plans are selected for execution.

Typically, this kind of composition is used when expecco is called from a QA system, such as Polarion or HP Quality Center, where individual "test sets" are composed out of a collection of existing test cases.

Notice, that this may lead to longer startup times, depending on the number of suites found in the suite directory, because suite files there will be opened and searched for matching test cases. If the same set of tests needs to be executed multiple times, it may be a good idea to use the "--saveSuite" option, to have the composed suite saved into a file for later reuse.

Also notice, that this works best, if testcase have unique names or are known by their ID (which is globally unique). If your test management system can provide unique identifiers, these should be used to name your testcases inside the suite (typically, a unique name of the test-case or requirement is used to name corresponding test-cases).
<br>(These options are only available in release &ge; 2.7)

*'''<code>--suiteDirectory <dirName></code>'''<br>defines the directory, where test suite files are searched for composed test plans. Test cases as specified in one of the options below must be found in one of the files present there. Notice, that the first file which contains a requested test case action will be chosen. Thus, you should ensure, that only one version of each suite is present there. Typically, an up-to-date test suite directory as checked out from the revision control system is specified here. If this argument is not given, test cases are searched in the list of explicitly listed suite files (".ets" arguments).<p>This option also specifies the directory where suites are found for remote execution (see description of SOAP and REST services below).</p><p></p>

*'''<code>--suiteTitle <string></code>'''<br>defines the name of the new test plan, which is created dynamically. This is used to control the labels in the generated report files.<p></p>

*'''<code>--testCaseNames <name-list></code>'''<br>defines the test cases to be included in the test by name. name-list is a list of comma-separated names of the individual test actions.<br>Please only use this option, if your testcases have unique names and are found only once in any suite found in the suite directory. Otherwise, the first suite which contains that name will be chosen (see below for better selection options).<p></p>

*'''<code>--testCaseFIDs <id-list></code>'''<br>defines the test cases to be included in the test by function ID. id-list is a list of comma-separated UUIDs of the individual test actions.<br>This option is probably not very user-friendly for a human, but allows for a calling program (or script) that the testcase is found even if it has been renamed in the meanwhile (remember that functional IDs are assigned once when an item is created and remain unchanged over the whole lifetime).<p></p>

*'''<code>--testCaseIDs <id-list></code>'''<br>defines the test cases to be included in the test by version ID. id-list is a list of comma-separated UUIDs of the individual test actions.<br>This option may be very unfriendly for a human user, but allows for a calling program (or script) to ensure that a particular testcase with a particular version is found and executed, even if the testcase has been renamed or modified in the meantime (remember that the ID is changed with every modification). If the same testcase is found in multiple suite files (i.e. in different versions), this will ensure that the correct version will be executed<p></p>

*'''<code>--saveSuite <fileName></code>'''<br>saves the generated as-hoq suite. Useful if you want to archive such a dynamically generated scatter-gather suite separately from the result file(s), or to automatically construct new suites. Notice that the ".elf" result file will always include the generated ad-hoq suite, so archival of the generated ad-hoq suite is only needed if you generate pdf, HTML or other non-elf reports.<p></p>

==== Test Parameters ====

*'''<code>--parameter &lt;fileName&gt;</code>''' / '''<code>-P &lt;fileName&gt;</code>'''<br>Load a parameter set from a file. A parameter set contains values for a test suite's top environment. This can be either in XML format, as generated with the [[Environment_Editor|"''Save-Parameter-Set''" menu function]], a CSV file, containing key-value pairs or a JSON file containing a JSON dictionary object.<p>Parameter files in either format can be created manually in a text editor, provided by a QM system (such as expecco ALM, HP Quality Center or similar), generated by another controlling program or generated by expecco itself via the "''Save-Parameter''" menu function of the [[Environment_Editor|environment editor]].</p><p>The parameter file may contain values for a subset of the environment variables. In this case, the values from the parameter file overwrite corresponding values present in the loaded test suite, leaving other values unchanged.</p>

*'''<code>--parameter:&lt;key&gt;=&lt;value&gt;</code>''' / '''<code>-P:&lt;key&gt;=&lt;value&gt;</code>'''<br>Sets an individual parameter for the next "--execute" argument.<p>If multiple "--execute" arguments are given (i.e. multiple suites are to be executed in sequence), these parameter values are collected and given to the next execution only, and overwrite corresponding values from either a parameter set (see above) or from the suite itself.</p><p>Thus, it is possible to execute the same suite with different parameters in one command line (see example above).<br>(this option is available with expecco vsn >= 2.10)</p>

==== Test Execution via Scripting ====
*'''<code>--scriptFile &lt;fileName&gt;</code>'''<br>read and execute a script from a file (see scripting below).

==== Reporting ====

*'''<code>--verdicts</code>'''<br>Send execution and result info in human readable format to the stderr output. (see [[#Verdicts Example|example below]].)<p></p>

*'''<code>--logFile <fileName></code>'''<br>Used to change the name of the generated log file, where stderr is written to.<br>This is only useful if running in server mode.<p></p>

*'''<code>--exitCode <n></code>'''<br>Defines the exit code to be used independent of the test outcome.<br>The default is 0 (zero) if all tests pass, and non-zero when they do not. However, some calling programs (make/jenkins,...) may misinterpret this exit code and treat the whole job as non-executable. Use this flag to prevent this. It is still possible to change the exitCode for a particular outcome by adding one of the following options after this option.<p></p>

*'''<code>--exitCodeOnFail <n></code>'''<br>Defines the exit code in case any test ends with a test-failure status.<br>The default is 0 (zero), so that when you run expecco out of make, Jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnError and exitCodeOnInconclusive values (see below), unless explicitly defined by those options.<p></p>

*'''<code>--exitCodeOnError <n></code>'''<br>Defines the exit code in case any test ends with a test-error status.<br>The default is 0 (zero), so that when you run expecco out of make, Jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute. This option also changes the exitCodeOnInconclusive values (see below), unless explicitly defined by that option.<p></p>

*'''<code>--exitCodeOnInconclusive <n></code>'''<br>Defines the exit code in case any test ends with an inconclusive status.<br>The default is 0 (zero), so that when you run expecco out of make, Jenkins or other tools which check for the exit status, the calling program does not interpret this status as if expecco itself failed to execute.<p></p>

*'''<code>--elfReportFile <elfFilename></code>'''<br>Writes a report in expecco's native XML logfile format. The report contains a lot of detail information and could be processed by an XSLT processor or a similar tool. It also contains enough additional information about test plans and actions so that expecco can redisplay the activity log tree from this file. The generated file can be opened directly via the command line ("expecco <file>.elf") or by double clicking on the elf-file in the operating system's desktop.<p></p>

*'''<code>--csvReportFile <csvFilename></code>'''<br>Writes a summary report in CSV format. Each row consists of:<br>
** ''TESTSUITE'' - the filename
** ''TESTPLAN''  - the test plan
** ''TESTCASE''  - the test case
** ''VERDICT''   - the test result; one of SUCCESS, FAILED, ERROR or INCONCLUSIVE
** ''INFO''      - additional info in case of failure
:Additional pseudo verdicts such as STARTTIME, ENDTIME etc. are written. A typical CVS output file can be found in the [[#CSV File Example|examples]].<p></p>

*'''<code>--textReportFile <textFilename></code>'''<br>Writes a summary report in a human readable textual format. A typical text output file can be found in the [[#Textual File Example|examples]].<p></p>

*'''<code>--xmlReportFile <xmlFilename></code>'''<br>Writes a report in XML format. The report contains a lot of detail information and could usually be processed by an XSLT processor or similar tool. A typical XML output file can be found in the [[#XML File Example|examples]].<p></p>

*'''<code>--pdfReportFile <pdfFilename></code>'''<br>Writes a summary report in pdf format.<p></p>

*'''<code>--htmlReportFile <htmlFilename></code>'''<br>Writes a summary report in HTML format.<p></p>

*'''<code>--junitReportFile <htmlFilename></code>'''<br>Writes a summary report in a JUnit compatible XML format. Useful, when expecco is to be started by Jenkins or similar driver programs.<p></p>

*'''<code>--polarionReportFile <htmlFilename></code>'''<br>Writes a summary report in an XML format which is especially suited for the Polarion QM tool. The structure of the generated XML is the same as with the JUnit format above, but a slightly different time format is used.<p></p>

*'''<code>--reportTemplateName <name></code>'''<br>Use the given report template (must be an element inside the test suite) for the following "--xxxReportFile" argument. If no such argument is given, the default template as defined in the suite is used.<p></p>

==== Services ====

*'''<code>--server</code>'''<br>Starts expecco in server mode. This combines the "''--service''", "''--infoService''" and "''--remoteControlService''" flags. All of those services as described below are started with that single command line argument.<p></p>

*'''<code>--service</code>'''<br>Starts expecco in server mode. In this mode, HTTP-SOAP and HTTP-REST requests can be used to remote-control expecco's execution; especially, to execute and monitor tests, and upload results. The most obvious use for this is for expecco to act as an execution host (test slave) for an expecco ALM or Polarion server.<br>However, because standard protocols are used, this may also be used to interface the execution engine to many other QM management or automation systems (e.g. HP Quality Center). The interface is described below.<p></p>

*'''<code>--infoService</code>'''<br>Provide an additional info service which allows for monitoring and control of an expecco server via a web browser (server mode only).<p></p>

*'''<code>--remoteControlService</code>'''<br>Provide an additional service to interact with a running test. Dialog requests, single stepping, starting, pausing and stopping of tests is possible via remote REST requests. This service is used by the Android remote control app, which is available upon request (server mode only).<p></p>

*'''<code>--port <portNr></code>'''<br>Used to change the HTTP and SOAP port numbers, when running in server mode.<br>The default is 9090 (server mode only).<p></p>

*'''<code>--scripting <portNr></code>'''<br>Enable scripting (remote control via Telnet ASCII interface) on portNr ([[#Scripting Example|see more below]]).<p></p>

*'''<code>--allowHost <hostName></code>'''<br>Allow hostName to connect to the scripting port. Repeat for multiple hosts (see more below).<p></p>

==== Utility Functions ====

*'''<code>--diff <file1> <file2></code>'''<br>Print differences between two test suites. This can be used e.g. to automatically generate log messages for a revision control system (please read the section on "Integration with Source Code Management System" below).<br>(This function is only available in release &ge; 2.7)<p></p>

=== Command Exit Status ===

*0 - all tests passed

*>0 various other errors (command line, file not found, etc.)

*101 - at least one test failed (FAIL status). This exitCode can be overwritten by a command line argument.

*102 - at least one test was inconclusive (INCONCLUSIVE status). This exitCode can be overwritten by a command line argument.

*103 - at least one test lead to an error (ERROR status). This exitCode can be overwritten by a command line argument.
<br>
The diff option returns 0 if the compared suites are the same, or 200+n, (where n is the number of differences) otherwise.

== Sample Outputs ==

The following output files were generated by executing the test suite from the file:
:"C:\Programme\exept\expecco\testsuites\projects\Example.ets"
which contains a single test plan named:
:"Example Testplan"
which contains three test cases named:
:"Test1"
:"Test2"
:"Test3-Should fail"
of which the first two are supposed to PASS and the last one generates an ERROR.

All timestamp information is written in ISO8601 format.

Be reminded that the following reports are condensed reports, which only contain a subset of the information contained in expecco's native ".elf" file format. The "elf" file contains all of the execution, trace and data-flow information and the original suite as executed. "elf"-files can be reloaded at any time into the expecco UI and the test be reexecuted. Also, any of the other reports can be regenerated, possibly with different report options (i.e. detail).

Thus it is highly recommended that these "elf" files are archived after a test run, in addition to any of the condensed report files (e.g. pdf or JUnit report).


=== CSV File Example ("<code>--csvReportFile</code>" option) ===

By default, entries are separated by ";"-characters. Additional double quotes (") are used to delimit strings with embedded ";" or spaces. Any double quote within such a string is doubled.
CSV is a simple and very common interchange format.
For example, CSV files can be imported into Microsoft Word, Excel and OpenOffice (and many other).

 TESTSUITE;TESTPLAN;TESTCASE;VERDICT;INFO
 ;;;StartTime;2008-10-31T08:57:13.689
 "C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test1;PASSED;  
 "C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test2;PASSED;  
 "C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";"Test3 - Should fail";ERROR;   
 ;;;EndTime;2008-10-31T08:57:18.746

=== XML File Example ("<code>--xmlReportFile</code>" option) ===

 <SummaryReport>
   <StartTime>2008-10-31T08:56:49.774</StartTime> 
   <TestSuite>
     <File>C:\Programme\exept\expecco\testsuites\projects\Example.ets</File> 
     <TestPlan>
       <Name>Example Testplan</Name> 
       <TestCase>
         <Name>Test 1</Name> 
         <Verdict>PASSED</Verdict> 
       </TestCase>
       <TestCase>
         <Name>Test 2</Name> 
         <Verdict>PASSED</Verdict> 
       </TestCase>
       <TestCase>
         <Name>Test 3 - Should fail</Name> 
         <Verdict>ERROR</Verdict> 
       </TestCase>
     </TestPlan>
   </TestSuite>
   <EndTime>2008-10-31T08:56:55.142</EndTime> 
 </SummaryReport>

This is not to be confused with the "elf" result file format, which is also XML based, but contains a lot more detail.

Notice also, that the JUnit report format ("<code>--junitReport</code>" option) is similar in structure but uses different tags.
JUnit reports are compatible to reports generated by Java JUnit frameworks.
They can thus be used to generate reports and trends in Jenkins/Hudson and other tools which understand the JUnit report format.

=== Textual File Example ("<code>--textReportFile</code>" option) ===

 Test Execution Summary
   Start: 2008-10-31 08:56:12.751
   TestSuite: "C:\Programme\exept\expecco\testsuites\projects\Example.ets
     TestPlan: Example Testplan
       Test 1 ....................... PASSED
       Test 2 ....................... PASSED
       Test 3 - Should fail ......... ERROR
   Finish: 2008-10-31 08:56:18.009


<!--Orginal:

--------------------------------------------------------------------------------------------------------------
TESTSUITE;TESTPLAN;TESTCASE;VERDICT;INFO
;;;StartTime;2008-10-31T08:57:13.689
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test1;PASSED;  
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";Test2;PASSED;  
"C:\Programme\exept\expecco\testsuites\projects\Example.ets";"Example Testplan";"Test3 - Should fail";ERROR;   
;;;EndTime;2008-10-31T08:57:18.746
--------------------------------------------------------------------------------------------------------------

----------------------------------------------------------------------------
<SummaryReport>
  <StartTime>2008-10-31T08:56:49.774</StartTime> 
  <TestSuite>
    <File>C:\Programme\exept\expecco\testsuites\projects\Example.ets</File> 
    <TestPlan>
      <Name>Example Testplan</Name> 
      <TestCase>
        <Name>Test 1</Name> 
        <Verdict>PASSED</Verdict> 
      </TestCase>
      <TestCase>
        <Name>Test 2</Name> 
        <Verdict>PASSED</Verdict> 
      </TestCase>
      <TestCase>
        <Name>Test 3 - Should fail</Name> 
        <Verdict>ERROR</Verdict> 
      </TestCase>
    </TestPlan>
  </TestSuite>
  <EndTime>2008-10-31T08:56:55.142</EndTime> 
</SummaryReport>
----------------------------------------------------------------------------

-------------------------------------------------------------------------
Test Execution Summary
  Start: 2008-10-31 08:56:12.751

  TestSuite: "C:\Programme\exept\expecco\testsuites\projects\Example.ets
    TestPlan: Example Testplan
      Test 1 ....................... PASSED
      Test 2 ....................... PASSED
      Test 3 - Should fail ......... ERROR

  Finish: 2008-10-31 08:56:18.009
------------------------------------------------------------------------- -->

=== Verdicts Example ===

the "<code>--verdicts</code>" option generates a simple trace on the standard error (to be redirected into a file):

 C:\selftest\commandLineArgs> expecco --noBanner --noTray --verdicts 
 --parameter paramesForTest.xpar --execute parameterTest.ets<br>
 Expecco [info]: start testSuite "parameterTest.ets"...
 Expecco [info]: using parameters "paramesForTest.xpar"...
 Expecco [info]: start testPlan "Test Parameters From CommandLine"
 Expecco [info]: start testCase "Validate Parameters"
 Expecco [info]: done testCase "Validate Parameters"; STATUS=PASSED
 Expecco [info]: done testPlan "Test Parameters From CommandLine"; STATUS=PASSED
 Expecco [info]: done testSuite "parameterTest.ets"; STATUS=PASSED

== Integration with Quality Management and Automation Tools ==

=== Integration with Jenkins ===

To have expecco tests being executed automatically by Jenkins, take the following example as a guideline. This is a real world setup, taken from our own setup within eXept.

# Create a test job, which is triggered by a successful build (or a change in the test suite repository)
# Check the "Block Build while prerequisite Jobs are Active" flag
# Check either the "Trigger from Source Code Management" or the "Trigger from other Job" flags
# Check "Abort build if it is Stuck" (just to make sure, that a faulty suite does not block Jenkins)
# Check "Fail the Build if Stuck" and give it a reasonable elastic Time-out Strategy (we use 300% of the last 10 builds, to make sure a longer execution time due to more test cases will not be interpreted as a stuck, and an extra timeout of 30 minutes. The timeout is very generous for the expected execution time of a few minutes).
# Check "Run xvnc during Build" to allow for monitoring, what is going on. This is also required, if the test needs a UI.
# Define the "Build Procedure" as "Execute Shell Script" (Unix/Linux) or "Execute Batch Job" (Windows)
# Enter a build procedure similar to the ours, which is:
#::<code>cd exept\expecco\application
#::del *.junit
#::expecco.com --noBanner --exitOnInternalError --noTray \
#::::--jUnitReportFile selfTestResult.junit \
#::::--execute ..\projects\expecco\eXpeccoSelfTest.ets
#::expecco.com --noBanner --noTray \
#::::--jUnitReportFile CommunicationWithExpeccoNETResult.junit \
#::::--execute ..\projects\expecco\CommunicationWithExpeccoNET.ets</code>
#:The details (especially paths and names) will of cause be different in your setup. The above uses the relative paths as it first changes the current directory to where the previous build has compiled the executable, which will of course not be the case in your setup.
# Define a "Post-build Action"
# Check "Publish JUnit Test Results"
# Enter a path expression to declare the location of the resulting reports. Here, we used:<PRE>exept\expecco\application\*.junit</PRE>
# Check the "Publish Test Attachments" flag, so the results will be presented in the Jenkins management console

That's it! Because expecco has been told to generate JUnit compatible report files, we can use Jenkins' existing JUnit support. However, the JUnit XML format does not support the full range of information which is present in the native expecco result files (especially the activity log and pin value information is not included). Therefore, it is a good idea to also generate a regular ".elf" (expecco log file) and add it to the archived build artefacts.

=== Integration with expecco ALM ===
Expecco and expecco ALM (formerly called "''expeccoNET''") have been originally designed to work together. Therefore, only a minimum setup is required:
# ensure that an expecco test execution slave is running on each test host (server farm, virtual machines, etc.). Depending on the operating system, this is either done by installing expecco as a service (Windows), or by adding appropriate startup actions to your "init.d" files (Unix).
# define the test host(s) in expecco ALM.
# (optionally) define the devices available and attached to the execution slave machine in expecco ALM

Expecco ALM will ask the expecco slaves about their operating system environment. So jobs will be automatically executed on matching CPU/OS machines. However, if tests require special resources (devices) to be attached, these must be defined and listed in expecco ALM as well. If your test has corresponding resource-requirements defined (see resources/inventory), expecco ALM will both ensure that the test will execute on the correct machine, and also reserve the resource during the execution. Also, test scheduling, if defined to be automatic, will be optimized to minimize resource usage, and to ensure that a higher number of tests can be executed in parallel.

=== Integration into a SOA Infrastructure ===

For this, expecco should be started on the test host(s) in so called "slave" mode.
In this mode, expecco awaits for execution commands via SOAP or REST, executes tests in the background and returns status information (progress) and results (reports).

Because tests may execute for a long time (hours or even days), the execution is performed asynchronously; first, the test has to be downloaded to the slave, then execution started. The start-command returns a ticket, which is a test-run-identifier, by which the execution progress can be queried (polled) while the test is running. Finally, a "finished" status is returned, upon which the result can be acquired via another service call.

Multiple such test slaves can be started on multiple machines, and each test slave may (if required) execute multiple tests in parallel (although this is usually limited to one, to avoid conflicts when external resources are accessed).

To start expecco in slave mode, use the command line:
 expecco --service

or, if the default port (9090) is not available, use:
 expecco --service --port 9090

The service interface is described below; typically, you can talk to expecco via:
 http://localhost:9090/expeccoService
or:
 http://localhost:9090/expeccoService/rest

The SOAP wsdl is returned via:
 http://localhost:9090/wsdl/ExpeccoSOAPService.wsdl

and - if the inforService is also running - general status information with:
 http://localhost:9090/info

=== Integration with HP Quality Center ===

This is described in the [[ HP Quality Center Plugin ]] document.

=== Integration with Polarion ===

This is described in the [[ Polarion Plugin]] document.

== Integration with Source Code Management Tools ==

=== Background Info on what is Contained in a ".ets" File ===

Expecco stores testsuites in a file with '.ets' extension (which stands for: "''Expecco-Test-Suite''") and result logs in '.elf' files (stands for: "''Expecco-Log-File''").
These are technically zip files - i.e. a bundle of individual files which can be extracted with the common zip command line tool (winzip under Windows systems, zip/unzip under Unix systems).

For example, "<code>unzip -l foo.ets</code>" lists the individual components, of which especially the block descriptions and attachments may be of interest.

Notice, that you have to be careful when ets-files are bundled with zip manually: for various consistency checks, expecco generates a validation signature of the components and saves this as an additional file inside the .ets file.
This signature file must be preserved and it must be consistent with the other zip-components. In effect, this means that an ets can only be constructed from the very same components, using the very same signature file as were extracted before. Otherwise, expecco refuses to load the ".ets" file later.

=== Version Management of ".ets" files ===

Unless a QA system like "expecco ALM" is used, ets-files can be stored and maintained in any other source code management (SCM) system, for example, CVS, SVN, hg/Mercurial, git, Perforce etc.
Make sure to store the .ets as binary file, and/or disable source expansion of version tag lines (for example, "$Header" or "$Id" in CVS). Consult your particular SCM system's documentation on how this is done.

As an alternative, it is possible to unzip the ets into individual components, store them separately, and zip them back into an ets, when a previous version is extracted from the SCM system. However, you must be careful to preserve the contents exactly as is, including the signature and other meta data, and not mix versions. I.e. all individual component files must be checkedIn/out in sync and as a group - it is not possible to update individual files from previous versions. The reason is that action blocks are referred to by their versionID, and these IDs will certainly be inconsistent, when previous versions of individual action blocks are mixed into another version's suite.

If, for whatever reason, you must checkin individual action blocks, we highly recommend to check in BOTH the bundled ets (and use that for later test execution), AND check in the individual components, and use only those for meta actions, such as comparison, documentation or other administrative tasks.

=== Generating Diff Lists or other Version Information ===

Many source code management systems allow for hook-scripts to be added to checkin/checkout actions, and/or to redefine the command to be used for diff-list generation.

For example, in the SVN system, an external diff tool can be defined. You could write a little shell or batch script, which calls expecco with the "<code>--diff</code>" option which is described above. Thus, you would get meaningful diff output even from checked in ets-bundle files.

The "<code>expecco --diff</code>" option is also useful as a command line tool to get diff lists - even if your SCM system does not allow for such automatic hooks.

== Scripting ==

Expecco can be scripted either by reading a script from a file or remote controlled via a telnet like command-line interface.
This is useful to execute complex test scenarios and meta tasks, to create or manipulate test suites automatically and for self-testing expecco by using another expecco to control its GUI.
It can also be used to execute and automate more complex scenarios without using expecco ALM.
<br>Example uses are:
* Sequentially load and/or execute all suites found in a folder, reimport libraries, save the updated suite
* Construct new suites by merging/selecting tests from other suites
* Bulk renaming, commenting, attributing etc.
* Change attachments inside a number of suites
* Controlling an application or web interface (via a GUI plugin) and saving a sequence of screen shots

By default, the scripting interface expects expressions in JavaScript syntax (but with a Smalltalk object model), similar to the language used for elementary block definition. However, the language can be changed to Smalltalk syntax via a "~" directive.

=== Script File Example ===

To control expecco via a scriptfile, use the "<code>--scriptFile &lt;filename&gt;</code>" command line argument, where <filename> must be a file containing JavaScript expressions.

For example, the following script file named "run3Suites.js" may contain the code:
<PRE>
    // Example for an automatic expecco script.
    // (loads and executes a number of test suites)
    //

    // to enable debugging in case of an error.
    // STXScriptingServer.errorDebugging(true);

    var files = [
        "foo.ets",
        "bar.ets",
        "baz.ets",
    ];


    Expecco::ExpeccoPreferences.current.automaticReimportOnLoad(true);
    Expecco::ExpeccoPreferences.current.checkForReimportableImportsOnLoad(true);
    Expecco::ExpeccoPreferences.current.checkForAnchestorOnAutomaticReimport(false);
    // Expecco::ExpeccoPreferences.current.libraryPath(importPathes);

    // --------------------

    function executeTestPlan ( aTestPlan ) {
       Stderr.nextPutLine("executing testplan "+aTestPlan.name()+"...");
       resultList = aTestPlan.execute();
       Stderr.nextPutLine("done.");
     }

    function runSuite(suiteFile) {
        var loadedProject;

        Stderr.nextPutLine("loading "+suiteFile+"...");
        expecco.loadProjectFromFile(suiteFile);
        loadedProject = expecco.project();

        if (loadedProject == null) {
            Stderr.nextPutLine("failed to load library "+suiteFile+".");
            Smalltalk.exit(1);
        } else {
            loadedProject.allTestPlansDo( executTestPlan );
        }
    };

    files.do(runSuite);
</PRE>

And can be executed with:

    expecco --scriptFile run3Suites.js

for windowless operation, use the "<code>--noWindow</code>" command line argument.
To speed up the startup, you can turn off the loading of plugins, with a "<code>--noPlugins</code>" argument (and possibly load any required plugins explicitly via additional plugin arguments).
Finally, enable debug messages with a "<code>--debug</code>" argument.
Thus, the recommended options for scripting are:

    expecco --debug --noPlugins --noWindow --scriptFile run3Suites.js

of course, this command line can be put into a shell (or batch) script file, and then executed with a single word command.

=== Telnet Scripting Example ===

The remote scripting service is enabled when a "<code>--scripting</code>" command line argument is given.
By default, the service only accepts connections from the local host (for security reasons). Using the "<code>--allowHost</code>" option, more hosts can be gained access to the scripting feature - but be aware, that this opens a potential security hole, as all of the internal functions can be accessed via the scripting system (and this includes the possibility to write files and call operating system services with the access rights of the one who started the scripting server).

When used with a remote script connection (telnet),
additional connection- and execution related commands are introduced by lines starting with the "~" (tilde) escape character (similar to telnet).
For example, "~." (tilde-period) is used to close the connection.
Press "~?" (tilde-question) for help.

The following is a trace of a typical scripting session (user input in bold):

 c:\programs\expecco> <b>expecco --scripting 8008</b>
 c:\programs\expecco>     ... expecco now running in the background with GUI ...
 ...
 c:\programs\expecco> <b>telnet localhost 8008</b>
 Welcome to Expecco (Type ~? for help)
 > <b>println(expecco);</b>
 an Expecco::Browser
 > <b>expecco.menuNewProject();</b>
 ...expecco performs the new-function from its menu...
 > <b>expecco.loadProjectFromFile("C:\Users\cg\testsuites\webedition\projects\BearerTest.ets");</b>
 ...expecco loads the testSuite...
 > <b>expecco.close();</b>
 > <b>~.</b>
 Lost Connection.
 c:\programs\expecco>

You can also start a scripting session without an initial expecco browser window:

 c:\programs\expecco> <b>expecco --noWindow --scripting 8008</b>
 c:\programs\expecco>     ... expecco now running in the background without GUI ...
 ...
 c:\programs\expecco> <b>telnet localhost 8008</b>
 Welcome to Expecco (Type ~? for help)
 > <b>println(expecco);</b>
 an Expecco::Browser
 > <b>expecco;</b>
 > <b>~v+</b> // turn result-printing on
 > <b>expecco</b>
 an Expecco::Browser
 > <b>~v-</b> // and off again
 > <b>expecco.loadProjectFromFile("~/SomeTest.ets");</b>
 ...expecco loads the testSuite...
 > <b>var blk = expecco.project.elementWithName("My Action");</b>
 > <b>blk.name("My Fun Action");</b>
 > <b>expecco.saveProjectToFile("~/ModifiedTest.ets");</b>
 > <b>expecco.close();</b>
 ><b>~.</b>
 Lost Connection.
 c:\programs\expecco>

== Scripting API Overview ==

A few objects are predefined by name; among them are "''expecco''", which refers to the browser itself (i.e. the UI) and "''environment''", which refers to a collection of variable bindings (this is a dictionary of interpreter variables - not to be confused with a variable environment as known inside an expecco activity block).
<BR>New variables can be defined with a "<code>var &lt;name&gt;;</code>" statement. For example:
<CODE><PRE>
    var ws;

    ws = new ExpeccoWorkspaceApplication;
    ws.open();
    ws.close();
</PRE></CODE>

==== expecco Object ====

The variable named "''expecco''" refers to the opened GUI-object, which represents the expecco application itself.

===== Expecco Functions =====

*'''project()'''<br>the current project
*'''currentApplication()'''<br>the current page (initially, there is only one)
*'''currentTreeApplication()'''<br>the current tree sub-application

*'''selectModelItem( anItem )'''<br>select an item and open an editor for it
*'''selectedModelItems()'''<br>returns a collection of selected items

===== Menu Functions =====
These execute the underlying menu functions (as if clicked by the user).

*'''menuNewProject()'''<br>creates a new testSuite
*'''menuOpen()'''<br>opens a dialog requesting a testSuite
*'''menuExit()'''<br>closes the expecco application

*'''loadProjectFromFile(fileNameString)'''<br>load a testSuite
*'''saveProjectToFile(fileNameString)'''<br>save the testSuite
*'''selectTestPlanWithName(testPlaneNameString)'''<br>select a testplan item by name
*'''selectTestPlanWithFunctionalId(uuid)'''<br>select a testplan item by uuid

*'''testSuite()'''<br>retrieves the testSuite object (see below)

===== Test Suite (Project) Functions =====
the project as returned by the above "project()" function provides access to its elements:
<br>(see also [[ Expecco API#Test Suite Project Functions]])

*'''authorName()'''<br>get the author name string
*'''authorName(aString)'''<br>set the author name string
*'''versionString()'''<br>get the version string
*'''versionString(aString)'''<br>set the version string
*'''projectsWorkingDirectory()'''<br>the directory, where attachments etc. are found
*'''ensureEnvironment()'''<br>an instantiated environment (concrete values). See below.
*'''elementWithName( nameString )'''<br>returns a matching element or null if not found
*'''elementWithId( aUUID )'''<br>returns that element or null if not present. (create the UUID with "<stringConstant>.asUUID" )
*'''elementWithFunctionalId( aUUID )'''<br>returns that element or null if not present

==== Environment Object ====

Environment objects are used to store key-value bindings for expecco variables. Environments form a hierarchy, where values are searched for in an environment's parent environment, if not present. This hierarchy follows the containing compound activity chain up to the project (= test suite) environment.
Additional temporary environments are kept by the executor and the browser, to keep temporary values for a single execution's or a single session's lifetime.

*'''at(key)'''<br>retrieves a value, given the name of the entry. Raises and error if no variable exists by that name.
*'''at_ifAbsent(key, default)'''<br>like above, but returns default if no variable exists by that name (instead of raising an error).
*'''includesKey(key)'''<br>true if a variable by that name exists, false otherwise.
*'''at_put(key, value)'''<br>store value as variable named key. Raises an error, in an attempt to change a readOnly variable
*'''environmentDescription()'''<br>returns the environment's description. This describes types, default values and read/write attributes per entry.
&nbsp;

==== EnvironmentDescription Object ====

This is a collection of entries which describe variables of an environment. It does only hold the description, not the bindings themselves; i.e. it contains the information required to instantiate an environment. EnvironmentDescriptions inherit from OrderedCollection and therefore entries are accessed via "at:" using a numeric index from 1 to the environmentDescription's size.

Entries (as per variable) provide the following protocol:

*'''name()'''<br>the name of the variable
*'''isReadOnly()'''<br>true if readonly
*'''defaultValue()'''<br>the initial value, assigned when the environment is created
*'''datatype()'''<br>the type of the variable
*'''comment()'''<br>description
&nbsp;

== Remote Controlling and Monitoring Expecco ==

Expecco itself can be automated by various mechanisms:

* via command line arguments (described in [[ #Command Line | "Command Line"]] above)

* via script files (see [[ #Script File Example | "Script File Example"]] above)

* via the telnet interface (see [[ #Telnet Scripting Example | "Telnet Scripting Example"]] above)

* via standard RPC mechanisms, such as SOAP or REST.

Especially the RPC mechanisms are useful to integrate expecco into the company test infrastructure.
Such interfaces are meant for programmatic control of an expecco slave from quality management, application life cycle and other scheduling tools.
Our own companion product, expecco ALM and third party tools, such as Polarion use these service interfaces.

Notice, that for integration into a Jenkins infrastructure, command line arguments or scripts may be a more cost effective means to control automated expecco testruns.

=== Expecco as a Slave Node in a Test Lab ===

The service interfaces are useful to control unmonitored slave machines in the network, among which expecco test execution jobs are scheduled by another program. Expecco ALM and other quality management tools use these to initiate test runs in a test server farm.
For this, the basic operations "download of a suite", "execute a suite" and "requesting execution results" are available as service calls.

Both SOAP and REST services are available, if expecco is started with the "''--server''" argument.
An optional "''--port''" argument allows for the HTTP port to be changed from the default (9090) on which expecco is listening.

For debugging and testing, the service can be also be started from the interactive UI, via expecco's main menu (in the "''Extras''" - "''Web-Services''" - "''Start / Stop''" menu items).

These services use HTTP requests as transport layer.

==== Expecco SOAP Service Interface ====

This accepts SOAP requests, via the URL "<code>/expeccoService</code>". I.e. the default URL is "<code>host:9090/expeccoService</code>".
A partial WSDL spec can be acquired from the running service via "<code>host:9090/wsdl/ExpeccoSOAPService.wsdl</code>" (partial, because it is currently not does not contain complete type information).

The service entries are:

===== Loading and Executing a Suite =====

The execute request is the main service entry. It passes the suite and also optional parameters.

The test suite can be bade available to expecco either by passing it with the request (as base64 CDATA), or by passing a URL from which expecco can fetch the suite itself.

The execute call contains the following fields:

 <message name="expecco_executeProject_v5_Request">
    <part name="id" type="UUID"/>
    <part name="testSuiteId" type="UUID"/>
    <part name="dataSource" type="xsd:string"/>
    <part name="dataSourceUri" type="xsd:string"/>
    <part name="environment" type="xsd:arrayType"/>
    <part name="testplans" type="xsd:arrayType"/>
    <part name="resources" type="xsd:arrayType"/>
    <part name="optionalParameters" type="xsd:arrayType"/>
  </message>

and responds with:

  <message name="expecco_executeProject_v5_Response">
    <part name="result" type="xsd:string"/>
  </message>

This call starts execution, and immediately returns a response, which consists of an identifier.
This identifier can later be used to ask expecco about the execution status. As a test may take a long time to finish,
it is useful to poll via status requests from time to time, to see if the execution has finished and to get progress status.

The parameters are:

* id - mandatory; a ticket ID; this should be a UUID-string, to avoid possible conflicts
* testSuiteId - mandatory; the UUID of the suite to execute. See below for details about download optimizations
* dataSource - optional; if present, this should contain the whole ets-file's contents as a Base64 encoded CDATA string
* dataSourceUri - optional; if present, this should be the URI from which expecco shall fetch the suite. See below for details
* environment - optional; top-level environment variable values. This can be used to provide alternative initial values for variables in the top level variable environment (the "Project-Environment")
* testplans - optional; a list of UUIDs of testplans to execute. If not present, all top-level testplans are executed
* resources - optional; a list of resources to be used by the test (see expecco ALM resource description)
* optionalParameters - optional; an array containing additional parameters as key-value elements.

The "optionalParameters" field:

A list of key-value elements (i.e. must have an even number of elements, of the form [k1 v1 k2 v2 ... kN vN] ).
Each key is an xsd:string, each value's type depends on the key, but all of them are currently also strings.
The list of supported parameters is open for future extension of the interface. Currently, the following are recognized:
* [ "generateLog" xsd:boolean ] - the boolean arg must be "true" or "false"
* [ "generatePDFReport" xsd:boolean ] - boolean arg, must be either "true" or "false"

The "testplans" field:

this allows selective execution of individual test plans and also individual test cases (from within a test plan) from the suite.
If not present, all test plans as present in the suite are executed.
If present, the testPlans parameter must be an xsdarray of pairs (i.e. each array element is again an xsdarray with 2 elements).
Each top level element describes one testplan to be executed. The first element of each being the testplan's UUID, the second another array, listing the testcases by UUID.
For example, if the suite contains three testplans, named "a", "b" and "c", with plan "a" having id-a and "b" having id-b as UUID.
A testPlans argument might look like:
<pre>
[
    [ id-a ]
    [ id-b [  id-tcb-1 id-tcb-2 ] ]
]
</pre>
and specify that testplan "a" should be executed fully (i.e. all test cases), and only the testcases tcb-1 and tcb-2 are to be executed from testplan "b".

The "environment" field:

-- to be described --

The "resources" field:

-- to be described --

The reply consists of the ticket-id, which has to be passed in further status requests.

===== Loading Only =====

It is also possible, to download a suite without execution, via the "download" request:

  <message name="expecco_downloadProject_Request">
    <part name="testSuiteId" type="xsd:string"/>
    <part name="dataSourceBase64" type="xsd:string"/>
    <part name="dataSourceUri" type="xsd:string"/>
    <part name="optionalParameters" type="xsd:arrayType"/>
  </message>

  <message name="expecco_downloadProject_Response">
    <part name="result" type="xsd:string"/>
  </message>

===== Download Optimization =====

Expecco remembers downloaded suites in a temporary folder, to avoid repeated transfers of possibly huge test suites.
If a URI is passed (but no base64 encoded data), expecco checks if the suite is already present on the test host,
and will not fetch it again, if already present. If not present, expecco will fetch the suite via a HTTP request from the URI.

If no URI is passed (i.e. both data and dataURI fields are empty), expecco will either respond with an error reply, if not present,
or with an OK response, if already present.

Thus, if you have to pass the suite as data (i.e. there is no file service available, from which expecco could fetch the suite),
it is recommended to first check if a suite is already present (by sending a download request without data) and check for an error return. If no error is reported, the suite is already there and no further download action is required. If there is an error response,
the client should send the suite with another download request, this time with a non-empty data field.

After any successful download (either via download, or via execute request), the suite can be executed by an execute request without data.

===== Execution by Suite File Name =====

An alternative to downloading suites is to 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.
The executeTestSuiteFile-request is used to execute one of the suites in that directory.

The call contains the following fields:

 <message name="expecco_executeTestSuiteFile_Request">
    <part name="id" type="UUID"/>
    <part name="fileName" type="xsd:string"/>
    <part name="environment" type="xsd:arrayType"/>
    <part name="testplans" type="xsd:arrayType"/>
    <part name="resources" type="xsd:arrayType"/>
    <part name="optionalParameters" type="xsd:arrayType"/>
 </message>

If successful, a ticketID is returned (same as above execute-request).

===== Status Request =====

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

  <message name="expecco_getExecutionInfo_Request">
    <part name="ticketId" type="UUID"/>
  </message>

  <message name="expecco_getExecutionInfo_Response">
    <part name="result" type="xsd:string"/>
  </message>

A client may have to send multiple "getExecutionInfo" requests, until a "finished" status is returned.
Expecco will keep the generated reports and log files in a temporary folder, until fetched via a getResult request.
This allows for both expecco and the client to be turned off and restarted, without loosing any status information.

===== Result Request =====

Once finished, reports and log files should be fetched from expecco.

  <message name="expecco_getResult_Request">
    <part name="ticketId" type="UUID"/>
    <part name="removeResultBoolean" type="xsd:string"/>
  </message>

  <message name="expecco_getResult_Response">
    <part name="result" type="xsd:string"/>
  </message>

After the "getResult" request, corresponding files are automatically removed from the temporary folder by expecco.

===== Terminate/Abort Request =====

Use this, to abort and terminate an ongoing test execution.
 
  <message name="expecco_killExecution_Request">
    <part name="ticketId" type="xsd:string"/>
  </message>

  <message name="expecco_killExecution_Response">
    <part name="result" type="xsd:string"/>
  </message>

===== Remove Ticket Request =====

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.
 
  <message name="expecco_killExecution_Request">
    <part name="ticketId" type="UUID"/>
  </message>

  <message name="expecco_killExecution_Response">
    <part name="result" type="xsd:string"/>
  </message>

===== 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.

  <message name="ping_Request">
  </message>

  <message name="ping_Response">
    <part name="result" type="xsd:array"/>
  </message>

===== Cleanup of Old Result/Log Files =====

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

  <message name="expecco_cleanupTempFiles_Request">
  </message>

  <message name="expecco_cleanupTempFiles_Response">
    <part name="result" type="xsd:string"/>
  </message>

===== Example Wire Protocol Trace =====

Client asks expecco to execute a suite.

<-- HTTP Request to expecco --
<pre>

POST / HTTP/1.1 
Connection: Keep-Alive 
User-Agent: Smalltalk/X 6.2.5.0 
Host: 127.0.0.1:9090 
Content-Length: 8925 
Content-Type: text/xml; charset="utf-8" 
SOAPAction: "" 

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope 
   xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
   xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
   xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
   env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">

 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_executeProject_v5 xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <optionalParameters xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        enc:arrayType="xsd:anyType[6]">
    <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateReport</item>
    <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
    <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">generateLog</item>
    <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
    <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">runAllTestcasesIfEmptyTestcaseList</item>
    <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">true</item>
   </optionalParameters>

   <testSuiteId xsi:type="UUID">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
   <testplans 
        xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        enc:arrayType="xsd:arrayType[1]">
        <item 
            xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
            xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
            env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
            enc:arrayType="xsd:anyType[2]">
            <item 
                env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
                xsi:type="xsd:string">f71c4700-7477-11df-a41b-00ff7b08316c
            </item>
            <item 
                xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
                xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" 
                enc:arrayType="xsd:anyType[0]">
            </item>
        </item>
   </testplans>
   <id xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</id>
   <dataSource xsi:null="1"/>
   <dataSourceUri xsi:type="xsd:string">http://127.0.0.1:8662/expeccoALM/tentativeObjects/a84b2d96-d133-47db-9fc2-17208b490bfe.a
   </dataSourceUri>
   <environment 
        xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        enc:arrayType="xsd:anyType[22]">
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Host__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">sr-laptop</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_LoginUserName__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">admin</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_FullUserName__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">.&#32;&#42;admin&#42;</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestHost__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">127.0.0.1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_UUID__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">e5c9cb30-a253-11e4-9f24-c48508c91d3c</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_ID__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">d4</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Name__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Test&#32;For&#32;Resources&#32;and&#32;Skills</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Definition_Summary__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string"></item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_UUID__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">200d93e1-a258-11e4-b9eb-c48508c91d3c</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_Run_ID__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">r14</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">__expeccoNET_TestSuite_VersionNumber__</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">1</item>
   </environment>

   <resources 
       xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
       xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
       enc:arrayType="xsd:anyType[28]">
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill2</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute2-2</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Float</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0.0</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;2&#32;eeee</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:integer">2</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Resource&#32;2</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Skill1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">attribute1-1</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">Integer</item>
     <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xsi:type="xsd:string">0</item>
   </resources>
  </m:expecco_executeProject_v5>
 </env:Body>
</env:Envelope>

</pre>

>-- response from expecco

<pre>

HTTP/1.1 200 OK 
Content-Type: text/xml 
Content-Length: 649 
Connection: Keep-Alive 

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_executeProject_v5Response xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <result xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</result>
  </m:expecco_executeProject_v5Response>
 </env:Body>
</env:Envelope>

</pre>

Client asks expecco for execution state

<-- HTTP Request to expecco

<pre>

POST / HTTP/1.1 
Connection: Keep-Alive 
User-Agent: Smalltalk/X 6.2.5.0 
Host: 127.0.0.1:9090 
Content-Length: 635 
Content-Type: text/xml; charset="utf-8" 
SOAPAction: "" 

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_getExecutionInfo xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <ticketId xsi:type="UUID">200d93e1-a258-11e4-b9eb-c48508c91d3c</ticketId>
  </m:expecco_getExecutionInfo>
 </env:Body>
</env:Envelope>

</pre>

>-- response from expecco (while still executing)

<pre>

HTTP/1.1 200 OK 
Content-Type: text/xml 
Content-Length: 2579 
Connection: Keep-Alive 

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <result>
    <executionResultState xsi:type="xsd:string">executingTestSuite</executionResultState>
    <currentActivity xsi:type="xsd:string">executing&#32;Neuer&#32;Testplan</currentActivity>
    <pdfReportFileURL xsi:null="1"/>
    <summaryResult>
     <summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
      <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
       <summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
        <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <detailString xsi:null="1"/>
         <resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
         <testplanItemName xsi:type="xsd:string">Neue&#32;Aktion</testplanItemName>
         <expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
        </item>
       </summaryTestPlanItems>
       <testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
       <expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
       <testPlanName xsi:null="1"/>
      </item>
     </summaryTestplanExecutionResults>
     <testSuiteName xsi:type="xsd:string">Test&#32;For&#32;Resources&#32;and&#32;Skills</testSuiteName>
     <testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
     <expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
    </summaryResult>
    <logFileURL xsi:null="1"/>
    <expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
    <executionProgress xsi:type="xsd:integer">0</executionProgress>
   </result>
  </m:expecco_getExecutionInfoResponse>
 </env:Body>
</env:Envelope>

</pre>

>-- response from expecco (after execution)

<pre>
HTTP/1.1 200 OK 
Content-Type: text/xml 
Content-Length: 2781 
Connection: Keep-Alive 

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_getExecutionInfoResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <result>
    <executionResultState xsi:type="xsd:string">finished</executionResultState>
    <currentActivity xsi:type="xsd:string">executing&#32;Neuer&#32;Testplan</currentActivity>
    <pdfReportFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf</pdfReportFileURL>
    <summaryResult>
     <summaryTestplanExecutionResults xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
      <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
       <summaryTestPlanItems xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" enc:arrayType="xsd:anyType[1]">
        <item env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <detailString xsi:null="1"/>
         <resultActivityState xsi:type="xsd:string">Successful</resultActivityState>
         <testplanItemName xsi:type="xsd:string">Neue&#32;Aktion</testplanItemName>
         <expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanItemExecutionResult</expeccoClass>
        </item>
       </summaryTestPlanItems>
       <testPlanId xsi:type="xsd:string">22623ef0-757d-11df-a41b-00ff7b08316c</testPlanId>
       <expeccoClass xsi:type="xsd:string">Expecco::SummaryTestPlanExecutionResult</expeccoClass>
       <testPlanName xsi:null="1"/>
      </item>
     </summaryTestplanExecutionResults>
     <testSuiteName xsi:type="xsd:string">Test&#32;For&#32;Resources&#32;and&#32;Skills</testSuiteName>
     <testSuiteId xsi:type="xsd:string">228168f0-747b-11df-a41b-00ff7b08316c</testSuiteId>
     <expeccoClass xsi:type="xsd:string">Expecco::SummaryTestSuiteExecutionResult</expeccoClass>
    </summaryResult>
    <logFileURL xsi:type="xsd:string">http://127.0.0.1:9090/expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf</logFileURL>
    <expeccoClass xsi:type="xsd:string">Expecco::SoapExecutionResult::SummaryEncoding</expeccoClass>
    <executionProgress xsi:type="xsd:integer">100</executionProgress>
   </result>
  </m:expecco_getExecutionInfoResponse>
 </env:Body>
</env:Envelope>

</pre>

Client fetches the report and log files from expecco:

<-- HTTP Request to expecco (fetch logfile)

<pre>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.elf HTTP/1.1 
Connection: Keep-Alive 
User-Agent: Mozilla/3.0N 
Host: 127.0.0.1:9090 
Accept-Encoding: chunked 
Accept-Language: en,* 
Accept-Charset: iso-8859-1,*,utf-8 
Accept: */* 
</PRE>

>-- HTTP response from expecco 

<PRE>
HTTP/1.1 200 OK 
Content-Type: application/x-expecco-logfile 
Content-Length: 12690 
Connection: Keep-Alive 
Cache-Control: max-age=86400 
Last-modified: Thu, 22 Jan 2015 17:32:50 GMT 

... a lot of elf-file data ...
</pre>

<-- HTTP Request to expecco (fetch pdf report)

<pre>
GET /expeccoResultFiles/ad8011e1-a25c-11e4-b9eb-c48508c91d3c.pdf HTTP/1.1 
Connection: Keep-Alive 
User-Agent: Mozilla/3.0N 
Host: 127.0.0.1:9090 
Accept-Encoding: chunked 
Accept-Language: en,* 
Accept-Charset: iso-8859-1,*,utf-8 
Accept: */* 
</pre>

>-- HTTP response from expecco

<pre>
HTTP/1.1 200 OK 
Content-Type: application/pdf 
Content-Length: 29768 
Connection: Keep-Alive 
Cache-Control: max-age=86400 
Last-modified: Thu, 22 Jan 2015 17:32:51 GMT 

... a lot of pdf data ...
</pre>

Client releases ticket (so expecco can remove the temporary data)

<-- HTTP Request to expecco

<pre>
POST / HTTP/1.1 
Connection: Keep-Alive 
User-Agent: Smalltalk/X 6.2.5.0 
Host: 127.0.0.1:9090 
Content-Length: 627 
Content-Type: text/xml; charset="utf-8" 
SOAPAction: "" 

<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_removeTicket xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <ticketId xsi:type="UUID">ad8011e1-a25c-11e4-b9eb-c48508c91d3c</ticketId>
  </m:expecco_removeTicket>
 </env:Body>
</env:Envelope>

</pre>

>-- HTTP response from expecco

<pre>
HTTP/1.1 200 OK 
Content-Type: text/xml 
Content-Length: 614 
Connection: Keep-Alive 

.....................
<?xml version="1.0" encoding="utf-8"?>

<env:Envelope xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
 <env:Body env:encodingStyle="http://www.expecco.net/soap/expecco/v1/">
  <m:expecco_removeTicketResponse xmlns:m="http://www.mars.dti.ne.jp/~umejava/smalltalk/soapOpera/rpc/">
   <result xsi:type="xsd:boolean">true</result>
  </m:expecco_removeTicketResponse>
 </env:Body>
</env:Envelope>

</pre>
===== Example Session Using "<code>wget</code>" =====

Using "wget" with SOAP is possible, but a little complicated, because correct SOAP requests have to be constructed, and ticket-numbers be extracted from responses. It is much easier with the REST service.

See below for a description.

==== Expecco REST Service Interface ====

This accepts REST requests, via the URL "<code>/expeccoService/rest</code>". I.e. the default URL is "<code>host:9090/expeccoService/rest</code>".

The REST service supports the same set of operations as the SOAP service described above, 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 all HTTP-GET requests, possibly with attached JSON encoded argument data.
The operation is determined by the URI: the last component is the operation name to be executed.

See details [[ Starting_expecco_via_Command_Line/rest | "expecco rest service interface"]].


=== Expecco Remote Control REST Service Interface ===

A secondary REST service is available to interact with a running test.
This service is used by the "expecco remote control App", which is available for Android devices (tablets and cell phones).

This accepts REST requests, via the URL "/remote". I.e. the default URL is "host:9090/remote".
A description of the supported REST calls can be acquired from the running service via "host:9090/remote/protocolInfo".

When this service is active, the standard Dialog requests (input boxes, with "OK"/"Cancel" buttons) will also be presented on the remote controlling app, and can be answered either on the PC-screen OR on a remote android device.
An obvious application of this is when the test system (hardware) needs manual interaction and you have to leave the workplace for this. Here, it is very convenient to be able to answer questions like "Insert Cable X and press OK to proceed" from a mobile device. Avoiding the need to walk back to the workplace to click on the "OK" button.

=== Expecco Short Status Information Service ===

This is a very simple HTTP service, which delivers a single page with a status overview.
This service is started when the "<code>--infoService</code>" or "<code>--server</code>" command line arguments are present.

This accepts HTTP requests, via the URL "/info".
I.e. the default URL is "<code>host:9090/info</code>".

The main use of this service is to quickly check the status of a testslave from a remote webbrowser,
without a need for a more complicated SOAP or REST service client.


Back to [[Online_Documentation#Topic:_Execution | Online Documentation]]